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F unctions and Messages by Category 

Note: The following is a list of all OS/2 and Presentation Manager functions and messages discussed 
in the book, organized according to the types of services they provide. Following the name of each 
function or message is the number of the figure in the book that provides a full explanation. 


CLIPBOARD 

MANAGEMENT 


WinOpenClipbrd 9.2 

WinQueryClipbrdData 9.5 

WinSetClipbrdData 9.3 

WinEmptyClipbrd 9.6 

WinCloseClipbrd 9.4 


COMMUNICATION 
(AMONG THREADS) 

DosSemSet 12.6 

DosSemClear 12.7 

DosSemWait 12.8 


' CONTROL WINDOW 
MANAGEMENT 

' General 


WM_COMMAND 

7.11 

WM_CONTROL 

8.18 

Edit Fields 

EM_SETTEXTLIMIT 

8.24 

List Boxes 

LM_IN SERTITEM 

8.32 

LM_QUERYSELECTION 

8.28 

LM_QUERYITEMTEXT 

8.29 

LM DELETEALL 

8.31 


Menus 

MM_SETITEMTEXT 

7.10 

MM_SETITEMATTR 

7.9 

WMJNITMENU 

7.7 

Scroll Bars 

SBM_SETSCROLLBAR 

4.9 

SBM_SETPOS 

4.17 

WM_HSCROLL 

4.12 

WMJVSCROLL 

4.18 


CURSOR 


MANAGEMENT 


WinCreateCursor 

5.3 

WinShowCursor 

5.5 

WinDestroyCursor 

5.6 


DIALOG BOX 


MANAGEMENT 


WinDlgBox 

8.9 

WinDefDlgProc 

8.10 

WinSendDlgltemMsg 

8.25 

WinDismissDlg 

8.11 

WM INITDLG 

8.19 







DISPLAY OF DATA 


WinMessageBox 

WinAlarm 


3.14 

6.9 


Erasing 

WinFillRect 2.23 

GpiErase 10.12 

WM_ERASEBACKGROUND 11.15 

Font Management 

GpiCreateLogFont 3.26 

GpiLoadFonts 3.18 

GpiQueryFonts 3.20 

GpiSetCharSet 3.27 

Graphics 

GpiMove 11.22 

GpiLine 11.23 

WinDra wBitmap 10.22 

WinDrawPointer 10.9 

Miscellanons 

WinScroll Window 4.14 

WinUpdate Window 4.16 

WM_PAINT 2.19 

Presentation Spaces 
WinlnvalidateRect 5.8 

WinBeginPaint 2.20 

WinEndPaint 2.21 

WinGetPS 3.19 

WinReleasePS 3.22 

Text Strings / Attributes 
GpiSetColor 3.29 

GpiSetBackColor 9.9 

GpiSetBackMix 9.8 

GpiCharString At 3.28 

WinDrawText 2.24 

WinUpper 7.20 


• ERROR PROCESSING 

WinGetLastError 3.11 


INFORMATION 


WinQuerySys Value 

11.1 


INITIALIZATION/ 


TERMINATION 


Winlnitialize 

2.2 

WinCreateMsgQueue 

2.3 

WinRegisterClass 

2.4 

WinDestroyMsgQueue 

2.14 

WinTerminate 

2.15 

WM_CREATE 

3.16 

WMJNITDLG 

8.19 

WM_CLOSE 

12.10 

WM_QUIT 

2.10 

WM_DESTROY 

10.11 


KEYBOARD 


MANAGEMENT 


WinGetKeyState 

11.16 

WinQueryFocus 

5.10 

WinSetFocus 

4.3 

WM_CHAR 

6.1 

WM_SETFOCUS 

5.1 


MEMORY 

MANAGEMENT 


Heap 

WinCreateHeap 

3.4 

WinLockHeap 

3.6 

WinAllocMem 

3.7 

WinFreeMem 

3.10 

WinDestroyHeap 

3.5 
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“ ntroduction 


The Presentation Manager is the windowed graphics interface 
provided with the OS/2 operating system, beginning with version 1.1. 
Although implemented as an extension to the basic operating system, 
the Presentation Manager is central to the purpose of OS/2. OS/2 was 
designed to run multiple programs, to allow communication among 
these programs, and to provide efficient interaction with the user. The 
Presentation Manager uses the basic facilities of OS/2 to run multiple 
applications within windows on a single screen, to exchange data 
among these applications, and to coordinate their input and output 
operations. The Presentation Manager thus realizes the fundamental 
design goals of OS/2; it fully exploits the basic operating-system 
capabilities and makes these features immediately available to the 
programmer and to the user. The designers of OS/2 consider the 
Presentation Manager to be the OS/2 programming environment of 
choice. 

Writing an application for the Presentation Manager offers many ad¬ 
vantages. First, the Presentation Manager uses a graphics display 
mode, which can display a higher density of information than a stand¬ 
ard text mode. The Presentation Manager is an ideal environment for 
graphics programs, or for programs that display a combination of 
graphics and text. Even applications that are primarily textual can 
benefit from running in a graphics environment. These programs can 
display text in a variety of fonts to produce a screen image that closely 
resembles the final printed copy; also, a graphics display mode enables 
the Presentation Manager to create the detailed icons and window ele¬ 
ments that allow the user to control the program. 

Another important advantage of the Presentation Manager is that the 
graphics interface is uniform from one application to another. The Presen¬ 
tation Manager provides a standard set of menus, dialog boxes, icons, and 
other components of the user interface. Applications that use these stand¬ 
ard facilities have a familiar appearance and are easy to learn. The interface 
is uniform not only among Presentation Manager applications, but also 
among applications written for similar environments, such as Microsoft 
Windows for MS-DOS. Additionally, by using these high-level facilities in 
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your programs, you can avoid the significant programming effort re¬ 
quired to develop your own user interface. 

The Presentation Manager also provides uniform channels for com¬ 
munication and exchange of data among separate programs. Accord¬ 
ingly, applications written for this environment can easily coordinate 
their activities and exchange data in order to form integrated software 
systems. 

Finally, under the Presentation Manager you can write programs that 
are device-independent (provided you follow the simple rules empha¬ 
sized in this book). For example, you can write a Presentation Manager 
application that will continue to run without modification as higher- 
resolution video devices are developed in the future (assuming only 
that the vendors of such devices supply the required device drivers for 
the Presentation Manager). 

Note also that the Presentation Manager forms an integral part of 
OS/2. Unlike Microsoft Windows, the Presentation Manager is in¬ 
cluded with every copy of the operating system (beginning with ver¬ 
sion 1.1), and automatically appears when the system is started. 
Accordingly, Presentation Manager applications, which integrate 
smoothly with this default environment, should be in great demand. 

Unfortunately, however, developing an application for the Presenta¬ 
tion Manager is not a trivial task for the programmer accustomed to 
traditional programming environments. There are two basic reasons for 
the initial difficulty in writing a Presentation Manager program. First, 
as you will see in this book, the basic architecture of a Presentation 
Manager application is radically different from that of a traditional pro¬ 
gram. Second, the Presentation Manager is designed to provide a 
sophisticated interface for a wide variety of graphics and text mode 
programs. Accordingly, the number of function calls it provides is vast, 
and many of these function calls accept a large and complex set of 
parameters and options. As you develop Presentation Manager applica¬ 
tions, you will likely come to appreciate the variety and subtlety of con¬ 
trol afforded by the Presentation Manager application program 
interface. Initially, however, the complexity can form an obstacle to 
learning and using the system. 

This book is written to help you overcome both of these difficulties. 
First, Part I of the book gently introduces you to the basic program ar¬ 
chitecture by tracing the development of a typical Presentation 
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Manager application—a text editor—beginning with a simple program 
shell and then gradually, chapter by chapter, adding features to this 
basic structure until it becomes a complete and useful application. 
Second, rather than presenting a large collection of functions at once, 
the book introduces the Presentation Manager services individually, 
and only as they are required in the development of the example pro¬ 
gram or in the treatment of the current topic. Thus, the description of 
the program interface unfolds gradually, and each function is explained 
within a context that clarifies its purpose. Also, unlike the technical 
documentation, this book does not have the burden of presenting all the 
features of each function; accordingly, the explanations of the functions 
focus on the essential elements and omit some of the confusing details 
that are important only for more advanced applications. 

The book is written to be a first learning resource as you approach the 
Presentation Manager. It is designed to facilitate the initial learning 
process so that you can begin to enjoy the benefits of programming 
under this environment as quickly as possible. 


BACKGROUND 
• AND REQUIRED TOOLS 

Given the ambitious scope of the book, there is little opportunity 
to explain programming basics. To understand the coding techniques 
and the example program listings, you should have a basic familiarity 
with the C language (the Bibliography recommends several books that 
will help you improve your C programming skills). Fortunately, the 
book uses no assembly language. 

Because all Presentation Manager applications run in the protected 
mode of OS/2, it would also help to have an understanding of the basic 
architecture of the Intel 80286 processor and the features of the OS/2 
operating-system kernel. The first chapter briefly summarizes the un¬ 
derlying facilities of OS/2; for additional information, see the 
Programmer's Guide to OS/2 or one of the other books on OS/2 kernel 
programming cited in the Bibliography. 

Programmers who have written applications for Microsoft Windows 
will find many features of the Presentation Manager quite familiar. 
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However, a background in Windows programming is not required to 
fully understand the techniques presented in this book. 

To prepare the example programs given in this book, and to write 
your own applications, you will need a programmer's toolkit designed 
specifically for developing Presentation Manager applications. The ex¬ 
ample programs were developed using the Microsoft OS/2 Software 
Development Kit, which includes the operating system and many 
programming tools. The following toolkit components were used to 
develop the programs in the book: the C compiler (version 5.1), the 
OS/2 header and library files, the Dialog Box Editor, the Icon Editor, 
the resource compiler, the MAKE utility, the linker, and the online help 
facility (QuickHelp). 


• OVERVIEW OF THE BOOK 

This book is divided into two parts. Part I describes the essential 
elements of a Presentation Manager application and provides the step- 
by-step techniques for writing a basic program. Part II explores a set of 
more advanced topics. 

Part I consists of Chapters 1 through 8. Chapter 1 summarizes the 
underlying facilities of OS/2 and the general features of the Presenta¬ 
tion Manager; the purpose of this chapter is to provide an overview of 
the context in which Presentation Manager applications run. The 
remaining chapters in Part I describe the specific techniques for 
developing a basic Presentation Manager application. These chapters 
are based upon a single example program: a Presentation Manager text 
editor. 

Chapter 2 describes how to write the basic program skeleton, which 
displays a window on the screen and writes a single line of text to this 
window. Although this program performs only a rudimentary set of 
tasks, it contains most of the essential elements of a Presentation 
Manager application. 

Chapter 3 then shows how to use the Presentation Manager memory- 
management functions to provide a buffer for storing the file data man¬ 
aged by the text editor. This chapter also describes how to display 
multiple lines of text within the window, how to handle errors that occur 
when calling Presentation Manager functions, and how to use the 
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Presentation Manager macros. The version of the example program 
presented in this chapter reads a text file and displays as many lines 
from the beginning of the file as will fit in the current program window. 

Chapter 4 illustrates the techniques for adding horizontal and verti¬ 
cal scroll bars to the program window, and for scrolling the window 
data as the user operates the scroll bars with the mouse. This chapter 
also explains how to provide a simple keyboard interface that reads the 
arrow keys and allows the user to scroll the file data without a mouse. 
The resulting version of the example program permits the user to read a 
text file and view any portion of this file within the window. 

Chapter 5 shows you how to manage a Presentation Manager cursor, 
which marks the current insertion point within the file. This chapter ex¬ 
plains how to create and display a cursor, and how to move it in 
response to keyboard commands. 

Chapter 6 explains how to implement a full keyboard interface, 
which processes normal character keys, as well as function keys, arrow 
keys, and other control keystrokes. This chapter also presents a set of 
routines for inserting and deleting data from the text file. The version 
of the example program given in Chapter 6 provides a full set of com¬ 
mands for adding and modifying file data. 

Chapter 7 describes the techniques for designing and installing 
Presentation Manager menus, which allow the user to select and ex¬ 
ecute program commands. This chapter also explains how to define ac¬ 
celerator keys, which are keystrokes that directly activate commands, 
bypassing the program menus. In addition. Chapter 7 presents the 
routines for implementing several of the menu commands. 

Chapter 8 describes the methods for designing, displaying, and 
managing dialog boxes. Dialog boxes are temporary windows used to 
display information and obtain data from the user. Dialog boxes are 
typically displayed when the user selects a menu item that requires ad¬ 
ditional information. This chapter also presents the final complete list¬ 
ing of the example program, which implements most of the essential 
features of a text editor. 

Part Two (Chapters 9 to 12) explores several advanced features of the 
Presentation Manager that can be used to enhance the applications you 
write. Chapter 9 describes how to write an interface to the Presentation 
Manager clipboard, which is a facility for transferring data within a 
single program or among separate applications. This chapter shows 
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you how to use the clipboard to implement cut, copy, and paste com¬ 
mands within the text editor presented in Part I. 

Chapter 10 covers the techniques for defining and using several 
types of Presentation Manager resources, including icons, pointers, bit¬ 
maps, strings, and programmer-defined resource types. By using 
resources, you can define graphic or textual data, store the data within 
special segments in the program file, and then load and use the data 
when required at run-time. 

Chapter 11 explains how to add a mouse interface to your applica¬ 
tion. Specifically, it shows how to read the position of the mouse 
pointer, how to control the shape of the pointer, and how to detect the 
state of the mouse buttons. The examples in this chapter also 
demonstrate several of the Presentation Manager graphics functions. 

Finally, Chapter 12 shows you how to improve the efficiency and 
responsiveness of your Presentation Manager applications by using 
multiple threads of execution. This chapter also explores the methods 
for smoothly synchronizing the activities of separate program threads. 
As an example, the chapter shows you how to implement a print 
routine as a secondary thread within the text editor presented in Part I. 

The appendices provide reference material that will be useful both 
while you read the book, and when you begin developing Presentation 
Manager applications. Appendix A contains a glossary that defines 
many of the terms you will encounter while working with OS/2 and the 
Presentation Manager. Appendix B briefly summarizes each of the 
operating-system services discussed in the text, and Appendix C 
provides the same information for the predefined Presentation 
Manager messages. The Bibliography lists books that are useful for ob¬ 
taining background information or for exploring specific topics in 
greater depth. Finally, the inside covers of the book provide a list of the 
system functions and messages discussed in the text, organized accord¬ 
ing to the types of services they perform. 


• HOW TO USE THE BOOK 


Although the book contains a large amount of reference material, 
it is primarily tutorial. Ideally, you should start by reading all of the 
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chapters in Part I in order; each of these chapters builds upon the con¬ 
cepts presented in the previous chapter. If desired, you can then read 
selected chapters in Part II. Each of these chapters relies upon the 
material of Part I, but does not necessarily depend upon the previous 
chapter. 

Note that each chapter has a primary topic indicated by its title, but 
also presents many subsidiary topics. In general, topics are explored as 
they are first encountered in the development of the example programs. 
Accordingly, the discussions in this book are presented in approximate¬ 
ly the same order in which you would normally encounter them when 
developing a Presentation Manager application. 

The book contains basic reference information covering a large set of 
the Presentation Manager functions and predefined messages. Once 
you have read the book, you will find this reference material useful for 
developing your own applications. Each of the functions or messages 
discussed in the text is described in an accompanying figure. You can 
locate the appropriate figure in one of two ways. First, if you are search¬ 
ing for a suitable function or message, you will find each of them listed 
on one of the inside covers of the book according to the type of service 
it provides, including a reference to the corresponding figure. Second, if 
you already know the name of the desired function or message, you can 
find a brief description and a figure reference in Appendix B (the func¬ 
tions) or Appendix C (the messages). 

The Presentation Manager documentation contains a large number 
of newly coined words and expressions, as well as common terms that 
have specific, nonconventional meanings. If a term is unfamiliar, or if 
you are uncertain of its meaning in a specific context, be sure to look it 
up in the glossary (Appendix A). 

Although the book does not supply formal programming exercises, 
many of the chapters have a section near the end that describes possible 
enhancements to the example code presented in that chapter; you can im¬ 
plement selected enhancements as exercises in Presentation Manager 
programming. Also, the chapters in Part II describe the general procedures 
for adding features to the example program given in Part I; you can imple¬ 
ment these procedures as additional programming exercises. Finally, the 
book may inspire you to explore advanced Presentation Manager features 
that could not be included, and to add these features to the example 
programs or to use them in developing your own applications. 
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COMPANION DISKETTE SET 
• AND PROGRAMMER'S TOOLS 

You can obtain a set of companion diskettes directly from the 
author. The two diskettes provide all program listings given in this 
book, plus all additional files needed to prepare the example programs. 

You can also order a full-featured version of the text editor presented 
in the book, which will allow you to write programs and other text files 
within a Presentation Manager window. This program provides an on¬ 
line help facility; cut, paste, and other block operations; search and 
replace commands; background compiling; macros; and many other 
features. 

Additionally, you can order a set of software tools for writing OS/2 
kernel and Presentation Manager applications. This tool set includes a 
useful collection of dynamic-link library functions, plus a set of 
programmer's utilities. Complete source code is provided for all func¬ 
tions and utilities. 

See the diskette offer in the back of the book for more information 
and for details on ordering these items. 
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M ost of this book is devoted to detailed, step-by-step pro¬ 
cedures for developing OS/2 Presentation Manager ap¬ 
plications. The purpose of the first chapter, however, is 
• to provide you with an overview of the general features 

of OS/2 and the Presentation Manager before you become immersed in 
the programming specifics given in the remainder of the book. 

The first section of this chapter summarizes the basic features of 
OS/2 that support all types of programs running under the system, in¬ 
cluding the Presentation Manager. The second section then introduces 
the general facilities of the Presentation Manager that support the spe¬ 
cial applications that are the topic of this book. Once you have read this 
chapter, you will have a good understanding of the general context in 
which Presentation Manager applications run, and you will be ready to 
begin learning the specific guidelines for developing these programs. 


• OS/2 FEATURES 

As mentioned in the Introduction, the Presentation Manager is an 
operating-system extension. It is implemented through the basic 
facilities of the OS/2 kernel that support all types of OS/2 programs. 
This section describes these basic features and explains how they relate 
to the Presentation Manager and the applications written for it. For an 
in-depth treatment of the OS/2 kernel and application program inter¬ 
face, refer to the Programmer's Guide to OS/2 or one of the other books on 
OS/2 kernel programming cited in the Bibliography. 


Screen Groups 

One of the primary features of OS/2 that distinguishes it from 
MS-DOS is the existence of multiple screen groups (also known as ses¬ 
sions). Each screen group consists of one or more programs that share 
the screen, keyboard, and mouse. You can run as many as 14 simul¬ 
taneous screen groups, but you can view and interact with only one of 
them at a time (which is known as the foreground screen group). The 
screen groups relegated to the background continue to run concurrently 
(except for the real mode screen group, described later in this section). 
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However, background screen groups no longer write to the physical 
screen or receive input from the actual keyboard or mouse; rather, 
screen output and keyboard or mouse input are temporarily stored in 
internal buffers known as virtual devices. You can switch among screen 
groups, bringing one at a time to the foreground, by pressing the Alt- 
Esc system hotkey, or by using the session manager, described later in 
this chapter. 

It is generally safest to run each application in a separate screen 
group so that its console I/O does not conflict with that of other 
programs. Thus, you can run several unrelated programs concurrently 
but can normally view only one of them at a time. However, if the 
Presentation Manager is installed, you can run multiple applications 
within a single screen group; within this screen group, you can view 
several programs simultaneously within windows on the screen. This 
arrangement is possible because the Presentation Manager channels all 
console I/O to the appropriate window, and Presentation Manager ap¬ 
plications are written to cooperate with other programs that share a 
common screen, keyboard, and mouse. (Note, however, that not all 
programs can run within a window of the Presentation Manager; some 
applications must run within separate screen groups. See the section on 
Types of Programs Managed by the Presentation Manager, later in the 
chapter.) 

There are two basic types of screen groups under OS/2. First, there 
can be a single real-mode screen group. Programs in this environment 
run in the real mode of the 80286 or 80386 processor, which emulates the 
operation of the 8086 and 8088 processors and therefore supports stand¬ 
ard MS-DOS applications. Accordingly, the real mode screen group is 
also called the DOS compatibility box , and it allows you to run MS-DOS 
software in addition to running applications written specifically for 
OS/2 in other screen groups. Note, however, that real mode applica¬ 
tions are suspended when this screen group is placed in the back¬ 
ground. The real mode screen group runs a copy of the 
COMMAND.COM command interpreter, and thus presents the same 
user interface as MS-DOS. 

Second, there are one or more protected mode screen groups. Programs 
in these screen groups run in the protected mode of the 80286 or 80386 
processor (therefore, OS/2 requires the 80286 or later model processor). 
The protected mode provides hardware support for multitasking, 
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allows programs to access a large virtual address space, and prevents 
individual programs from sabotaging other applications or the operat¬ 
ing system. Programs written for the protected mode use the same basic 
instruction set as real mode applications; however, they must obey cer¬ 
tain rules, and under OS/2 they require a special .EXE file header. 
Therefore, you need to use a compiler and linker designed specifically 
to generate protected mode programs. The features of OS/2 discussed 
in the remainder of this section apply only to protected mode screen 
groups. Note that you can run a copy of the protected mode command 
interpreter (CMD.EXE) in any protected mode screen group, which can 
be used to execute commands or load and run programs in a manner 
similar to MS-DOS. 

The Presentation Manager and the applications it manages run 
within a protected mode screen group; these programs therefore benefit 
from all the features of the protected mode, and must abide by the 
guidelines for writing protected mode programs. The Presentation 
Manager provides an alternative to the standard command-line inter¬ 
face. Note that it is possible to simultaneously run a collection of ap¬ 
plications within the Presentation Manager screen group, several 
protected mode programs within other screen groups, and an MS-DOS 
application in the DOS compatibility box. 

Running multiple screen groups requires a session manager to help 
you start new screen groups or switch to screen groups that are already 
running. Under OS/2 version 1.0 (which does not include the Presenta¬ 
tion Manager), the session manager is a text-mode shell program that 
occupies its own screen group; you can activate this program using the 
Ctrl-Esc system hotkey. In versions of OS/2 that include the Presenta¬ 
tion Manager (1.1 and later), the text-mode session manager is replaced 
by a graphical User Interface Shell that runs under the Presentation 
Manager, and therefore appears within windows in the Presenta¬ 
tion Manager screen group (the elements of this shell are described later 
in the chapter). 

Figure 1.1 illustrates the multiple screen groups in a version of OS/2 
that includes the Presentation Manager and that is configured to con¬ 
tain a DOS compatibility box. See the section on Types of Programs 
Managed by the Presentation Manager, later in the chapter, for an ex¬ 
planation of the types of applications that can run in each of these 
screen groups. 
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• Figure 1.1: 

OS/2 screen groups 


Multitasking 

and Interprocess Communication 

OS/2 supports multitasking at three distinct levels. Running mul¬ 
tiple concurrent screen groups, discussed in the previous section, repre¬ 
sents the highest level. As the next level of multitasking, OS/2 provides 
facilities for executing several programs simultaneously within a single 
protected mode screen group. The Presentation Manager uses these 
facilities to run multiple applications within windows on the screen. 
Also, a given Presentation Manager application can execute other 
programs as concurrent child processes. For example, the text editor 
presented in this book could execute a compiler as a child process and 
continue providing editing functions while the compiler runs. See 
Chapter 12 for more information on managing multiple processes. 

The lowest level of multitasking under OS/2 is its support for multi¬ 
ple threads of execution within a single program. It is possible to ex¬ 
ecute several sections of the same program simultaneously. Using 
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multiple threads is an important technique in writing Presentation 
Manager applications, and is discussed in Chapter 12. 

OS/2 also provides a large set of functions for interprocess com¬ 
munication, which allow the various tasks in the system to exchange 
data and synchronize their activities. Chapter 12 explains the use of 
semaphores within a Presentation Manager application for synchro¬ 
nizing the actions of several threads of execution. 


Virtual Memory 

Under the real mode of Intel processors, a memory address con¬ 
sists of a 16-bit physical segment address and a 16-bit offset within that 
segment. In the protected mode, however, the physical segment ad¬ 
dress is replaced with a 16-bit selector. The selector is not a physical 
address, but rather is an index into a table in memory known as a 
descriptor table ; the index points to an entry in this table termed a seg¬ 
ment descriptor. The segment descriptor contains the actual physical 
memory address of the segment, as well as other information regarding 
the segment. Note that under OS/2, memory segments have variable 
lengths, with a maximum length of 64 kilobytes. See Figures 1.2 and 1.3 
for a comparison of the addressing mechanisms used in real and 
protected modes. 

The use of selectors and segment descriptors in the protected mode of¬ 
fers many advantages. First, the operating system can allocate memory 
to application programs in excess of the amount of physical memory in¬ 
stalled in the machine. Segments that do not fit into physical memory 
can be temporarily stored on disk; the segment descriptor contains a bit 
indicating whether the segment is currently present in memory or has 
been swapped to the disk. This larger-than-life address space is known 
as virtual memory. Virtual memory not only allows protected mode ap¬ 
plications to contain considerably more code and data than would be 
possible under the real mode, but also simplifies programming. A pro¬ 
gram directly accesses all segments that have been allocated to it as if 
they were entirely present in memory; the processor and operating sys¬ 
tem invisibly handle all the details of swapping and rearranging mem¬ 
ory segments. 

For example, an application such as the text editor developed in this 
book can read an entire large file directly into memory; if the file size 
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exceeds the amount of free memory, the operating system will automat¬ 
ically store the excess data on disk and retrieve it when the program ad¬ 
dresses it. A similar application under MS-DOS would typically have to 
read only a portion of the file at a time, and explicitly maintain a set of 
temporary disk files to store modified data. 

A second advantage of the virtual memory addressing scheme is that 
it allows the system to differentiate code and data segments (the seg¬ 
ment descriptor contains a bit indicating whether the associated 
segment is executable). The operating system does not normally allow a 
program to modify a code segment; since a program cannot corrupt its 
own code, several instances of the same program that are loaded into 
memory can safely share the same code segment, resulting in an efficient 
use of memory. (In contrast, data segments either can be private for each 
instance of a program, or can be shared by several instances.) 



MEMORY 

i 







Segment 




Base of Segment 


(address) 

-^ 








Offset 


Offset 


m 

f 

Target Location 




• Figure 1.2: 

The real mode addressing scheme 
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The ability to share code segments has an important implication for 
Presentation Manager applications such as the text editor developed in 
this book. A useful editor should allow you to open several files and 
view them simultaneously in separate windows on the screen. Under the 
Presentation Manager, you can efficiently run separate instances of 
the program in distinct windows, each instance managing a different 
file. The program logic, therefore, does not have to deal with multiple 
files, buffers, and viewing windows. Also, the clipboard facility dis¬ 
cussed in Chapter 9 allows you to copy data from one window to 
another as easily as if the windows were managed by the same program. 

A third advantage of the virtual addressing mode is that it allows the 
system to prevent one application from corrupting another program or 
the operating system itself. The virtual memory mechanism contributes 
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• Figure 1.3: 

The protected mode addressing scheme 
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to a high level of protection in several ways. First, the descriptors for 
segments that are private to a given process are contained in a local 
descriptor table that can be accessed only by that process or by the 
operating system; thus, a process cannot normally access segments that 
it does not own. (Note that there is also a single global descriptor table that 
can be used by any process to access segments shared by the entire sys¬ 
tem. Under OS/2, these segments are employed for such purposes as 
storing system-wide information; however, the segments are marked so 
that application programs can read but not modify them. Note also that 
OS/2 allows two or more processes to share a specially designated seg¬ 
ment by placing descriptors pointing to this segment within the local 
descriptor tables of each process.) 

The system also enforces protection by recording the length of each 
segment in the descriptor table. If a program attempts to address 
beyond the end of a segment it owns, a protection fault results, which is a 
processor event that causes branching to an operating-system error¬ 
handling routine. OS/2 displays a message, terminates the offending 
program, and allows other programs to continue running unharmed. 
For example, when developing a Presentation Manager program you 
will generally encounter a protection fault if you address beyond the 
end of an array or use an uninitialized pointer. Although protection 
faults may be disconcerting, experiencing them is vastly superior to 
having to reboot the computer under a nonprotected operating system 
such as MS-DOS. 

Finally, the operating system protects itself by assigning each process 
a low privilege level. Under the 80286/386 processor, processes run at 
one of four distinct privilege levels. The OS/2 kernel operates at the 
highest level, and generally assigns application programs the lowest 
level. The privilege level of each code segment is recorded together with 
the other segment information in the descriptor table. As a result of 
their low privilege level, application programs are prevented from ac¬ 
cessing the code and data belonging to the operating system, and are 
restricted from using certain machine instructions that could affect the 
entire system. 

As a consequence of the memory protection mechanisms, a Presenta¬ 
tion Manager application can access only those segments that the 
operating system has explicitly allocated for it. The loader allocates 
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memory for the program's code and data segments at load-time; once 
the program begins running, you can dynamically allocate and release 
additional segments by calling the appropriate Presentation Manager 
or OS/2 services. Chapter 3 explains how to use Presentation Manager 
functions to allocate and manage dynamic memory 


Dynamic Linking 

In addition to the standard linking mechanism used by MS-DOS, 
OS/2 supports a radically new process known as dynamic linking. 
Under the standard linking method, the linker must bind the target 
code for all call instructions directly into the executable file. Figure 1.4 
illustrates the standard linking procedure for an MS-DOS or OS/2 pro¬ 
gram that calls routines belonging to a conventional function library. 
The linker physically combines the program object code (contained in 
an .OBJ file) with the object code for any library modules that are called 
(contained in .LIB files), producing a single executable file on the disk. 
When the program is run, this entire file is loaded into memory, 
generating a single executable image containing both program and 
function library code. 

In contrast. Figure 1.5 illustrates the dynamic linking procedure for 
an OS/2 protected mode application that calls external functions 
belonging to a dynamic-link library. The primary distinguishing feature 
of the dynamic linking mechanism is that the external function code is 
not bound into the executable (.EXE) file, but rather is stored in a 
dynamic-link library file (with a .DLL extension), which is kept on the 
user's disk and is read into memory when the program is loaded. In 
other words, binding of code is delayed from link-time to load-time. 

In the same manner as the standard linking mechanism, the linker 
processes both an object file (.OBJ) and a library file (.LIB). Although the 
library file used for dynamic linking is given the usual .LIB extension, it 
is a special file known as an import library. An import library does not 
contain the actual function code; rather, for each dynamic-link function, 
it contains a definition record that gives the name of the dynamic-link 
library file that contains the function, and the entry point of the func¬ 
tion within this library. This information is stored in the .EXE file header 
in relocation records that are used when the program is loaded. Thus, ex¬ 
ternal function references are resolved not by binding in actual code. 
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but by writing a record for each function that tells the loader how to 
resolve the references to the function when the program is run. 

When the program is run, the loader first reads the program code 
into memory; it then loads all referenced dynamic-link library files that 



e Figure 1.4: 

The standard linking mechanism 



have not already been loaded. Finally it "fixes up" all references within 
the program code to dynamic-link functions by supplying the actual far 
address (that is, selector and offset) of the function in memory. Thus, 
calls to dynamic-link functions become direct intersegment calls to the 
entry points of the functions in memory 

An important feature of dynamic-link libraries not indicated in Fig¬ 
ure 1.5 is that several concurrent applications can share a single 
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The dynamic linking mechanism 
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dynamic-link library module that has been loaded into memory. 
A dynamic-link module is loaded when it is first referenced by an ap¬ 
plication program (a client). When subsequent applications reference 
this same library, the loader does not read in additional copies but rather 
allows the applications to share the library code segments that have al¬ 
ready been loaded. When the last client terminates (that is, when the ref¬ 
erence count goes to 0), the dynamic-link library is freed from memory. 
Note that a dynamic-link library module has an opportunity to perform 
initializations either when it is first loaded into memory or whenever 
the module is first referenced by subsequent client programs. 

In addition to the advantage of being able to share dynamic-link 
library code among multiple applications and thereby reduce memory 
requirements, dynamic linking offers several other advantages over the 
standard linking mechanism. First, with the standard linking method, a 
separate copy of the library code must be stored in each .EXE file on 
disk. With dynamic linking, however, each .EXE file stores only the 
names and entry points of the functions; only a single copy of the code 
is stored on disk (in a .DLL file), and therefore disk space is saved. 

Second, if the code in a standard library file is modified, all applica¬ 
tions that use the library must be recompiled (and possibly 
redistributed to the users); changes can be made to dynamic-link 
libraries, however, that will globally affect the behavior of all calling 
programs without the need to recompile these programs. 

Finally, although loading the first application that references a 
dynamic-link library is slower than loading a traditionally linked pro¬ 
gram (since separate files must be read rather than a single executable 
image), loading all subsequent applications that use the same library is 
faster, because the .EXE files are smaller and the library code is already 
in memory. 

The dynamic linking mechanism is important for Presentation 
Manager applications for several reasons. First, the OS/2 application 
program interface (API) is implemented as a set of dynamic-link library 
modules. The OS/2 API is the basic set of operating-system services 
that support all types of programs in the system; many of these func¬ 
tions are used by the Presentation Manager and can be called by Presen¬ 
tation Manager applications. The OS/2 API services have the prefixes 
Dos, Vio, Kbd f and Mon, and they are briefly described in the next sec¬ 
tion. In this book, these functions are classified as the OS/2 API and are 
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distinguished from the Presentation Manager API functions discussed in 
the last section of the chapter. 

Because the operating-system services are supplied as dynamic-link 
libraries, accessing them from high-level languages is very efficient; 
rather than requiring an indirect interface function such as intdos in the 
C library, invocations to operating-system services are simple direct 
calls to the OS/2 code in memory, and they use the standard high-level 
language function-calling syntax. For example, the following C state¬ 
ment generates a direct call to the OS/2 service that obtains the current 
disk drive: 

DosQCurDisk (SDriveNuinber, SLogicalDriveMap) ; 

The code for the OS/2 API services is contained in a variety of dynamic- 
link libraries, such as DOSCALLl.DLL and VIOCALLS.DLL. 

A second reason for the importance of the dynamic linking 
mechanism is that the Presentation Manager itself is implemented as a 
collection of dynamic-link modules. A Presentation Manager applica¬ 
tion is one that calls dynamic-link functions belonging to the Presenta¬ 
tion Manager API. As you begin developing a Presentation Manager 
application, you will notice that although the program calls a large 
number of Presentation Manager functions, the .EXE file remains quite 
small. The small size is due to the fact that the executable file does not 
contain the actual Presentation Manager function code, but only 
dynamic-link records in the .EXE header. The actual function code is 
stored in dynamic-link libraries with names such as PMWIN.DLL on 
your disk and on the disk of the ultimate user of the program. When the 
first Presentation Manager application is run (normally the User Inter¬ 
face Shell), the loading process is quite lengthy, since a great amount of 
dynamic-link code must be loaded and initialized. Subsequent Presen¬ 
tation Manager applications, however, load quickly and use the 
dynamic-link code already present in memory. 

Note that although the Presentation Manager is an extension added 
to the original version of OS/2, the protocol for calling its functions is 
identical to that of the basic OS/2 API. Such seamless extensions to the 
operating system are made possible through the dynamic linking 
mechanism. A final reason for the importance of dynamic linking is that 
any software developer can provide custom extensions to the operating 
system (or to the Presentation Manager in particular) by writing a set of 
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functions and packaging them as a dynamic-link module. These func¬ 
tions can be called in the same manner as the OS/2 and Presentation 
Manager API services, can be accessed from any programming lan¬ 
guage, and can be shared by all running programs. (OS/Tools for the 
Presentation Manager, described in the diskette offer at the end of the 
book, is an example of such a package. See Chapter 10 of the 
Programmer's Guide to OS/2 for instructions on developing your own 
dynamic-link libraries.) 

The OS/2 

Application Program Interface 

As mentioned in the previous section, the services of the OS/2 ap¬ 
plication program interface (API) are implemented as dynamic-link 
libraries and can be called directly by OS/2 kernel programs (that is, non- 
Presentation Manager applications); many of these functions can also 
be called by Presentation Manager applications. The OS/2 API func¬ 
tions fall into four basic categories; the first three letters of the function 
name indicate the general category of the function. For example, Vio- 
WrtCharStr belongs to the set of video functions. The following are the 
four groups of OS/2 API functions: 


Prefix 

Purpose of Functions 

Dos 

General-purpose system functions 

Kbd 

Keyboard-management functions 

Mou 

Mouse functions 

Vio 

Screen-management functions 


The general-purpose Dos functions provide a wide variety of ser¬ 
vices. These functions can be divided into the following general clas¬ 
sifications according to the type of services they provide: 

• Program startup information 

t) Memory management 

® Disk file and character device I/O 
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• Disk, directory, and file management 

• Low-level device control 

• Management of threads 

® Management of processes 

• Management of screen groups 

• Interprocess communication 

• Time and date management 

® National language support 

• Run-time dynamic linking 

• Device monitor management 

• Error handling 

• Additional functions 

Most of the Dos functions can be called by Presentation Manager ap¬ 
plications; these functions provide many services not offered by the 
Presentation Manager API. Some of the Dos functions, however, may be 
incompatible with the Presentation Manager environment, such as 
those for low-level device control and device monitor management. 
Also, a Presentation Manager application cannot use the function Dos- 
Write to generate screen output. Note that many C library functions, 
such as fopen and read, ultimately call OS/2 Dos services. 

The Kbd, Mou, and Vio functions provide a comprehensive set of ser¬ 
vices for managing specific devices. Presentation Manager applications, 
however, should not call any of the Kbd or Mou services; rather, they 
should use the special Presentation Manager API services and messages 
(explained in Chapter 2). Note that certain Presentation Manager ap¬ 
plications (those that use the advanced Vio functions mentioned at the 
end of the chapter) can use a large subset of the OS/2 Vio functions; the 
programs discussed in this book, however, cannot call OS/2 Vio func¬ 
tions (advanced Vio applications are beyond the scope of this book). 

When writing a Presentation Manager application, it may be possible 
to obtain a given service through the Presentation Manager API, either 
through the Dos functions of the OS/2 API, or through the C library. For 
example, you can dynamically allocate blocks of memory using the 
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Presentation Manager heap-management functions (described in Chap¬ 
ter 3), through OS/2 API services, or by means of C library functions. 
The programs in this book use Presentation Manager functions when¬ 
ever possible (because these functions are the topic of the book), and C 
library functions for services not provided by the Presentation Manager 
(because these functions are familiar to C programmers). In certain 
cases, however, it might be more efficient to call OS/2 API functions 
directly. 

Note that if you call functions belonging to the OS/2 API, you must 
specify the appropriate import library when linking the application. 
This library is named DOSCALLS.LIB in version 1.0 of OS/2, and 
OS2.LIB in version 1.1; consult your documentation for the correct 
name. To learn more about the OS/2 API functions, see the OS/2 
Programmer's Toolkit Programmer's Reference or the Programmer's Guide 
to OS/2. 


PRESENTATION 
. MANAGER FEATURES 

This section provides a brief overview of some of the general fea¬ 
tures of the Presentation Manager to help you gain an understanding 
of the context in which Presentation Manager applications run. Most of 
the features of the Presentation Manager are explored in subsequent 
chapters when they are first encountered while developing the example 
application that forms the heart of the book. This section covers the fol¬ 
lowing introductory topics: 

« The User Interface Shell 

# The types of programs managed by the Presentation Manager 

• The Presentation Manager API 


The User Interface Shell 

When a version of OS/2 including the Presentation Manager is 
started, the User Interface Shell is normally the first application to begin 
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running (provided that this shell is specified with the PROTSHELL 
command in the configuration file). The User Interface Shell consists of 
a collection of Presentation Manager applications that run within win¬ 
dows in the Presentation Manager screen group. This shell replaces the 
text-mode session manager used in OS/2 version 1.0; it also replaces 
the standard command-line interface of the protected mode command 
interpreter (CMD.EXE). Once the shell is running, you can use it to load 
and run other applications (Presentation Manager as well as kernel 
programs), to switch to applications that are already running, to 
manage files and directories, and to set Presentation Manager system 
parameters. Presentation Manager applications run within windows of 
various sizes, which are normally arranged in an overlapping fashion 
(this arrangement is picturesquely described as cascaded ; you can op¬ 
tionally have the Presentation Manager position windows in a tiled, or 
side-by-side, arrangement). 

The following are the basic components of the User Interface Shell 
that are briefly described in this section (note that these components 
may vary with different versions and releases of the operating system): 

• The Task Manager window 

• The Program Starter window 

• The Presentation Manager Control Panel 

® The Presentation Manager Filing System 


The Task Manager Window 

You can activate the Task Manager window from any other pro¬ 
gram in the system by pressing the Ctrl-Esc key combination. This win¬ 
dow displays a list of currently running applications; you can 
immediately activate any of these programs by selecting it from this list. 
You can also terminate a running application directly from the Task 
Manager window, without first activating the program and stopping it 
through the normal program commands. In addition, the Task Manager 
allows you to save a list of programs and the data files these programs 
use, so that the specified configuration of programs and data files will 
automatically be established when the system is restarted. Finally, the 
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Task Manager allows you to shut down the system in preparation for 
turning off the machine; this procedure automatically terminates all 
running programs. 

Note that the Task Manager handles not only applications running 
within Presentation Manager windows, but also kernel programs in 
other screen groups. If you have configured the system to include the 
DOS compatibility box, the DOS command prompt appears in the list 
of running programs; you can switch to this screen group and run MS- 
DOS applications from the command prompt. 


The Program Starter Window 

The Program Starter window allows you to start new protected 
mode programs. This window displays a list of applications that have 
been installed; you can run a program by selecting it from this list. Also, 
you can add programs to the list, delete programs, or modify the infor¬ 
mation that is maintained for each program (such as the parameters and 
the startup directory). The list of programs is organized into groups, 
and you can choose the particular group you would like to view. The 
Program Starter window allows you to add, delete, or rename groups. 
Note that this window can be used to start applications within the 
Presentation Manager screen group as well as kernel programs running 
in other protected mode screen groups. 

The Program Starter window additionally allows you to run one or 
more copies of the protected mode command interpreter (CMD.EXE) so 
that you can start programs in the traditional manner from the OS/2 com¬ 
mand prompt. You can run the command interpreter either within a win¬ 
dow of the Presentation Manager, or in another screen group (in which 
case, it will use the entire screen). Note that you can also start programs 
from the Presentation Manager Filing System, described below. 


The Presentation Manager Control Panel 

You can use the Presentation Manager Control Panel to set a wide 
variety of parameters that affect the behavior of Presentation Manager 
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applications. The following are among the operations you can perform 
using this utility: 

• Set the system date and time 

® Adjust the blink rate of the cursor 

• Modify the behavior of the mouse 

• Select window colors and border style 

• Specify country-specific information 

® Manage the printer, serial port, and other devices 

• Add new character fonts 

The Presentation Manager Filing System 

The Presentation Manager Filing System is a windowed environ¬ 
ment that performs most of the directory- and file-management functions 
traditionally executed from a command-line prompt. This utility graphi¬ 
cally displays directories and files in a treelike representation; you can 
view various sections of the directory structure of a given disk in one or 
more windows, and select directories and files directly from this display 
Once one or more directories or files have been selected, you can perform 
any of the normal operations on them. For example, you can start a pro¬ 
gram, copy a file, or create a directory You can perform these operations 
through menus and dialog boxes. Additionally, you can execute many 
operations by using the mouse directly on the appropriate icon. For ex¬ 
ample, you can double-click the mouse on an icon representing an ex¬ 
ecutable file in order to run the program; also, you can drag icons with the 
mouse to copy or move files from one directory to another. 


Types of Programs 

Managed by the Presentation Manager 

As mentioned in the previous section, the Presentation Manager 
User Interface Shell allows you to run or switch to any program in the 
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system. From the perspective of the Presentation Manager, there are 
four basic program classifications: 

1. MS-DOS applications running in the real mode screen group 

2. Protected mode kernel applications that cannot run within a win¬ 
dow of the Presentation Manager 

3. Protected mode kernel applications that can run within a 
window of the Presentation Manager 

4. Presentation Manager applications; that is, programs written 
specifically for the Presentation Manager 

MS-DOS Applications 

MS-DOS applications can be run only if you have installed the real 
mode screen group (using the PROTECTONLY=NO configuration 
command). You can start these applications by selecting the DOS com¬ 
mand prompt from the Task Manager and running the programs from 
the command line. MS-DOS programs are suspended when you switch 
away from the real mode screen group. 

Kernel Applications 

That Cannot Run in a Window 

Kernel applications are those that use the basic OS/2 API services. 
These are applications that have not been written specifically for the 
Presentation Manager and therefore do not call Presentation Manager 
API functions. Many kernel applications can run within a window in 
the Presentation Manager screen group; the programs in this category, 
however, cannot run within a window because they perform some ac¬ 
tion that is incompatible with the Presentation Manager environment. 
The following are among the actions that would render a kernel pro¬ 
gram incompatible with the Presentation Manager: 

• Writing directly to the physical video buffer 

• Switching video modes 
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«> Altering the video state by calling the OS/2 API function 
VioSetState 

<> Directly programming the video controller registers 

ti Replacing video, keyboard, or mouse functions (through 
VioRegister, KbdRegisfer, or MouRegister) 

«> Installing a keyboard or mouse monitor 

Note that kernel graphics programs need to perform one or more of 
these prohibited actions and are therefore excluded from running 
within a Presentation Manager window. 


Kernel Applications That Can Run in a Window 

Text mode kernel applications that perform I/O through the Vio, 
KM, and Mou functions of the OS/2 API, and do not perform any of the 
forbidden actions listed in the previous section, can generally run either 
within a window of the Presentation Manager or within a separate 
screen group. Although programs in this category can be run within a 
window that is controlled by the user through a basic set of system 
commands, they cannot take advantage of the extensive set of functions 
available for programs written specifically for the Presentation 
Manager (they cannot, for example, use menus, dialog boxes, or 
graphics functions). 

Note that some of the Presentation Manager documentation includes 
this category of programs under the description "Presentation Manager 
applications." However, in this book (for lack of any other term) 
"Presentation Manager application" refers exclusively to a true Presenta¬ 
tion Manager program as described in the next section. 


Presentation Manager Applications 

This final category consists of applications that conform to the ex¬ 
acting program architecture specified by the Presentation Manager, 
which will be described throughout the remainder of this book. These 
programs can—and must—run within a Presentation Manager window 
and have full access to the vast array of services and features offered by 
the Presentation Manager. As mentioned previously in this chapter. 
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these programs can use many of the Dos functions of the OS/2 API, but 
should not call Kbd or Mou services, and only applications that make 
proper use of the advanced Vio Presentation Manager functions (men¬ 
tioned in the next section) may call OS/2 Vio services. 


Comments 

The text editor developed in this book is, of course, a Presentation 
Manager application as defined in this section. Note that applications in 
the last three categories (the protected mode programs) should have a 
flag in their .EXE file headers indicating to which of these three 
categories they belong. This flag enables the Presentation Manager to 
handle these programs correctly when they are loaded. The flag, how¬ 
ever, may be absent from protected mode applications prepared with 
earlier versions of the linker; such unmarked kernel programs cannot 
run within a window (unless they are run through the Program Starter 
window and you have explicitly changed the installation information 
to indicate that the program can be run in a window). Microsoft, how¬ 
ever, provides a utility (MARKEXE.EXE) that enables you to correctly 
mark the .EXE header for these programs. 


The Presentation Manager API 

The reward for conforming to the exacting architecture specified 
by the Presentation Manager is the use of the vast collection of services 
belonging to the Presentation Manager API. Only true Presentation 
Manager applications, as defined in the previous sections, can call these 
functions. An explanation of the Presentation Manager API will unfold 
gradually in the subsequent chapters; this section merely lists the 
general function categories. Like the OS/2 API described earlier, the 
first three letters of a function name indicate its general category. The 
following are the groups of Presentation Manager API functions: 


Prefix 

Purpose of Functions 

Dev 

Functions for managing devices 

Gpi 

Graphics functions 



Orientation 25 • 


Spl Print spooler functions 

Vio Advanced Vio functions for displaying character- 

based data; applications that use these services may 
also call many of the Vio functions of the OS/2 kernel 
(these functions are not discussed in this book) 

Win Window-management and general-purpose Presenta¬ 

tion Manager functions 

As comprehensive as this set of functions may be, it does not exhaust 
the resources available to Presentation Manager applications. Presenta¬ 
tion Manager applications can also obtain a great number of services by 
sending messages to window procedures belonging to the system. This 
concept will not likely make sense at this point, but will be fully ex¬ 
plained in Chapter 4. 


• CONCLUSION 

This chapter has provided a brief overview of the context in which 
Presentation Manager applications run. It has summarized the general 
features of the OS/2 kernel and the Presentation Manager user inter¬ 
face. It has also introduced the Presentation Manager programming in¬ 
terface, which will be described in subsequent chapters. The remaining 
chapters in this book explore the specifics of creating a Presentation 
Manager application. 
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his chapter presents the rudiments of the Presentation 
Manager text editor that will slowly evolve, chapter by 
chapter, into a complete and useful application. The ver¬ 
sion given here simply displays a window on the screen 
and prints a line of text at the top of the window. You will see, however, 
that constructing even a minimal Presentation Manager application re¬ 
quires writing several procedures and calling quite a number of functions. 

This program contains most of the essential elements of a Presenta¬ 
tion Manager application and provides a basic framework for sub¬ 
sequent versions. Even though it seems that the Presentation Manager 
exacts a large overhead merely to place a window on the screen, this 
window is not a simple inert object. A window cannot be placed on the 
screen with other programs unless it has a basic set of capabilities. The 
standard window created in this chapter has components that allow 
you to move it on the screen, change its size, minimize or maximize it, 
and terminate the program. You can perform these actions either 
through a menu or by acting on a set of graphic objects with the mouse. 
Furthermore, the window must be able to repaint itself whenever any 
of its data are destroyed as the user moves and manipulates the objects 
on the screen. 

In this chapter, you will learn how an ordinary C program becomes a 
Presentation Manager application; you will learn the message-based ar¬ 
chitecture of Presentation Manager programs; and you will learn how 
to display data within a window. You will also become familiar with 
several important services of the Presentation Manager API, and two 
Presentation Manager messages. 


BECOMING A PRESENTATION 
• MANAGER APPLICATION 

When you write a Presentation Manager application in the C lan¬ 
guage, you must include the header file OS2.H, which provides a large 
number of vital function declarations, type definitions, and constant 
definitions for both the basic OS/2 API and for the Presentation 
Manager API. Also furnished is a collection of macros useful for 
manipulating the data used by Presentation Manager functions and 
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messages (see Table 3.2 in Chapter 3 for a description of these macros). 
The header information is actually contained in a collection of include 
files, which OS2.H incorporates in your program through a series of 
nested #include statements. Since the total quantity of header informa¬ 
tion is quite large, only the most commonly used portions are included 
by default (otherwise, the compiler would waste time processing un¬ 
necessary data). See Chapter 3 and Table 3.1 for an explanation of how 
you can incorporate additional portions of the header information in 
your program by defining specific constants before including OS2.H. 

Figure 2.1 lists the function main belonging to the Presentation 
Manager application presented in this chapter (note that the program is 
listed in its entirety in Figure 2.27, at the end of the chapter). This func¬ 
tion performs the essential steps required of a Presentation Manager ap¬ 
plication. By performing these steps, a program becomes a Presentation 
Manager application, with all appertaining rights, privileges, and 
honors. Specifically, a program obtains the right to run within the 
Presentation Manager screen group, and it gains access to the vast col¬ 
lection of Presentation Manager services. The following is a list of these 
essential steps: 

1. Initialize the Presentation Manager 

2. Create a message queue 

3. Register a window class 

4. Create a window 

5. Get and dispatch messages 

6. Release Presentation Manager resources 


Step 1: Initialize 

the Presentation Manager 

A Presentation Manager application must first call the function 
Winlnitialize to initialize the Presentation Manager system for the cur¬ 
rent program and to obtain an anchor block handle. The anchor block 
handle is a value that identifies the application to the Presentation 



void main () 


HAB HAncBlk; 

HMQ HMesQue; 

HWND HFrame, HClient; 

QMSG QueMess; 

ULONG CtlData = 

FCF_MINMAX 

FCF_SHELLPOSITION 

FCF_SIZEBORDER 

FCF_SYSMENU 

FCF_TASKLIST 

FCF TITLEBAR; 


/* Anchor block handle. 

/* Message queue handle. 

/* Frame/client window handles. 

/* Message queue structure. 

/* Control windows to include. 

/* Minimize/maximize box. 

/* Make window visible on screen. 

/* Wide sizing border. 

/* System menu. 

/* Display program name in Task Manager. 
/* Title bar. 


/*** Initialize the Presentation Manager and obtain an anchor block handle. **/ 


HAncBlk = Winlnitialize 

( 0 ) ; 


/* Returns an anchor block handle. 

/* Initialization options: must be 0. 


/*** create a message queue for the current thread. **************************/ 

HMesQue = WinCreateMsgQueue /* Returns a message queue handle. */ 

(HAncBlk, /* Anchor block handle. */ 

0); /* Minimum queue size: 0 means default size.*/ 

/*** Register a window procedure. ********************************************/ 


WinRegisterClass 
(HAncBlk, 
"MAIN", 
WndProc, 

0L, 

0 ) ; 


/* Anchor block handle. 

/* Window class name. 

/* Window procedure associated with class. 
/* Class style: no styles specified. 

/* Bytes of data storage for each window. 


/*** create a standard window. ***********************************************/ 


HFrame = WinCreateStdWindow /* Returns handle to frame window. 


(HWND_DESKTOP, 

WS_VISIBLE, 

&CtlData, 

"MAIN", 

": PM Text Editor", 

0L, 

0 , 

Or 

SHClient); 


/* Parent window handle. */ 
/* Frame window style. */ 
/* Address of control data. */ 
/* Client window class name. */ 
/* Text for title bar. */ 
/* Client window style: none specified. */ 
/* Resource module handle: none. */ 
/* Resource identification: none. */ 
/* Address to receive client window hand. */ 


/*** Main message-handling loop. *********************************************/ 


while (WinGetMsg 
(HAncBlk, 
&QueMess, 

0 , 

0 , 

0 )) 


/* Get messages until WM_QUIT. 

/* Anchor block handle. 

/* Address of message structure. 
/* Window filter: any window. 

/* First message identifier: n/a. 
/* Last message identifier: n/a. 


• Figure 2.1: 

The function main of the example program 
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WinDispatchMsg (HAncBlk,&QueMess) 

; /* Dispatch messages. 

*/ 

/*** Relinquish Presentation Manager 

resources and terminate application. 

V 

WinDestroyWindow (HFrame); 

/* 

Eliminate the window. 

V 

WinDestroyMsgQueue (HMesQue); 

/* 

Eliminate the message queue. 

*/ 

WinTerminate (HAncBlk); 

/* 

Sever ties with the Presentation 

V 


/* 

Manager and release resources. 

*/ 

} /* end main */ 





• Figure 2.1: 

The function main of the example program (continued) 


Manager; you must save this number and pass it as the first parameter 
to several other Presentation Manager functions. 

Winlnitialize is described in Figure 2.2. As each new Presentation 
Manager function is encountered in the discussions in this book, it is 
described in an accompanying figure. Note that these descriptions focus 
on the features relevant to the techniques presented in the book, and do 
not always include all of the options available for a given function. For 
complete details, and for documentation on functions not treated in the 
book, consult the OS/2 programming reference cited in the Bibliog¬ 
raphy. Note also that Appendix B provides an alphabetical summary of 
the functions discussed in this book, and the inside book covers list these 
functions according to the types of services they provide. 

The function Winlnitialize is declared as follows within one of the 
OS/2 header files that is incorporated in your program when you in¬ 
clude OS2.H: 

HAB APIENTRY Winlnitialize (USHORT); 

The special types HAB, APIENTRY, and USHORT are defined within 
the OS/2 header files. HAB is a type identifier for an anchor block 
handle; it resolves, through several layers of type definitions, to the 
basic C type 


void far * 
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Winlnitialize 

Purpose: 

Initializes the Presentation Manager system for use by the 
current program. 

Prototype: 

HAB APIENTRY Winlnitialize 

(ushort fs Opt ions); Initialization options; must be NULL. 

Return Value: 

An anchor block handle. 

Notes: 

An application must call this function before it can use the 
other services of the Presentation Manager. The anchor block 
handle should be saved so that it can be passed to sub¬ 
sequent Presentation Manager functions. 


© Figure 2.2: 

The Winlnitialize Presentation Manager function 

APIENTRY is a type identifier for API functions. It is equivalent to the 
C type 

pascal far 

The Presentation Manager API services (as well as all OS/2 API ser¬ 
vices and dynamic-link library functions) are far functions, meaning 
that they are located in a separate segment in memory and are called 
through an address consisting of both a segment selector and an offset. 
These functions are also of type pascal, which implies the following 
conventions: 

© Parameters are pushed on the stack in the same order that they 
are listed in the parameter list (by default in C, they are pushed 
in the opposite order). 
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® The function must remove the parameters from the stack before 
returning (the default in C is for the calling program to remove 
all parameters from the stack). 

® Each function has a fixed number of parameters (this is a result 
of the first two features; a default C function can accept a vari¬ 
able number of parameters). 

® The function name is converted to uppercase before being placed 
in the object file (by default, Microsoft C preserves the case of 
function names and places an underscore at the beginning of the 
name). 

Finally, the type identifier USHORT is equivalent to the C type 

unsigned int 

Note that the function main in Figure 2.1 declares the variable HAno 
Blk using the same type identifier, HAB, that is used in the function 
declaration in the OS/2 header files; this variable stores the anchor 
block handle returned by Winlnitialize. It is generally easiest simply to 
use the type definitions given in the function declarations and 
documentation, without paying attention to the equivalent basic C 
types. These definitions are used consistently throughout the header 
files and the technical documentation, and within this book. They pro¬ 
vide more information regarding the purpose of the object than the 
simple C data types (for example, knowing that a variable is a handle to 
an anchor block is more useful than knowing merely that it is a void far 
pointer). Also, it is possible that the basic C types could change if the 
Presentation Manager were ported to another computer system (for ex¬ 
ample, USHORT might be defined as an unsigned short); if you have 
consistently used the OS/2 type definitions, your program types will 
remain valid. 

Note that to facilitate using this book in conjunction with the Presen¬ 
tation Manager technical documentation, the function descriptions use 
the same parameter names found in this documentation. These names 
begin with a prefix in lowercase letters, which indicates the type of the 
parameter (the data type, such as pch, which is a far pointer to a charac¬ 
ter, or the general use of the parameter, such as f, which is a flag). Fol¬ 
lowing the prefix is an optional identifier, which begins with an 
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uppercase letter and identifies the specific instance of the general type. 
For example, the parameter pfnWndProc (passed to WinRegisterClass 
and listed in Figure 2.4) is a pointer to a function (pfn) that is used 
specifically to pass the address of the window procedure (WndProc). 


Step 2: Create a Message Queue 

The function main now calls WinCreateMsgQueue (Figure 2.3) to 
create a message queue. A message queue is a data structure that receives 


WinCreateMsgQueue 

Purpose: 

Establishes a message queue that receives messages sent to 
all windows created by the current thread. 

Prototype: 

HMQ APIENTRY WinCreateMsgQueue 

(HAS hab, Anchor block handle obtained by a prior call 

to Winlnitialize. 

SHORT cmsg) ; Maximum size of the queue; a value of 0 

requests the default size. 

Return Value: 

A message queue handle, or NULL if unsuccessful. 

Notes: 

You should call this function after Winlnitialize, but before 
calling other Presentation Manager functions. A given 
thread can call this function only once. 

Related Function: 

Winlnitialize (Figure 2.2) 

• Figure 2.3: 

The WinCreateMsgQueue Presentation Manager function 
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and stores messages sent to all windows created by the current program 
thread; an application must establish a message queue before it can cre¬ 
ate a window. The program presented in this chapter consists of a single 
thread and creates several windows. The system places messages sent 
to any of these windows within the queue created by the call to Win- 
CreafeMsgQueue. As you will see shortly, the system sends messages 
to a window to notify it of a wide variety of events; for example, it sends 
a specific message when the window needs to redraw a portion of its 
data. You will also soon learn how to process these messages. Note that 
a value of 0 is passed as the second parameter, which causes the func¬ 
tion to use the default queue size. 

WinCreateMsgQueue accepts the anchor block handle returned by 
Winlnitialize and returns a message queue handle (of type HMQ, 
stored in the variable HMesQue). The message queue handle is saved 
so that it can later be passed to the function that destroys the message 
queue before program termination (WinDestroyMsgQueue). Note that 
WinCreateMsgQueue, like many Presentation Manager functions, 
returns a value of NULL if it is unsuccessful (NULL is defined as 0 in the 
C include files STDDEF.H and STDIO.H). The topic of testing for error 
return codes, and displaying error messages within message boxes, is 
introduced in Chapter 3. 

Note that in a multiple-thread application (discussed in Chapter 12), 
every thread that creates one or more windows must call WinCreate¬ 
MsgQueue to establish a message queue; furthermore, a given thread 
can create only one message queue. 


Step 3: Register a Window Class 

Next, the function maim calls WinRegisterClass (Figure 2.4) to create 
a window class. Every window created under the Presentation Manager 
belongs to a window class that defines a window procedure and other in¬ 
formation (such as default window styles). A window procedure is the 
function that processes messages sent to a given window; when a message 
is extracted from the message queue and dispatched, the system invokes 
the window procedure associated with the target window (extracting and 
dispatching messages is described under step 5). 
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© 


WinRegisterClass 

Purpose: 

Registers a window class. 
Prototype: 

BOOL APIENTRY WinRegisterClass 


(HAB hab, 

Anchor block handle obtained 
from Winlnitialize. 

PSZ pszClassName, 

Pointer to a null-terminated 
string containing the class 
name to be associated with the 
window procedure. 

PFNWP pfnWndProc, 

Address of the window 
procedure that is to be 
associated with the class name. 

ULONG flStyle, 

The default window style, 
which can be one or more of 
the class styles (CSJ listed in 
Table 2.1; styles specified when 
the window is created are 
added to the default styles 
specified with this parameter. 

USHORT cbWindowData); 

Bytes of storage that should be 
reserved for each window 
belonging to this class that is 
created; this data can be 
accessed by functions such as 
WinSetWindowUShort and 
WinQueryWindowUShort. 


Return Value: 

TRUE if successful, and FALSE if an error occurs. 

Related Functions: 

WinCreateStdWindow (Figure 2.5) 
WinCreateWindow 


• Figure 2.4: 

The WinRegisterClass Presentation Manager function 
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As you will see, when a window is created, it is assigned to a window 
class; using object-oriented terminology, the window is said to be an in¬ 
stance of this class. A window can be assigned to a pveTegisteved window 
class provided by the Presentation Manager for various types of win¬ 
dows; in this case, the system supplies the window procedure that 
processes the messages sent to this window. System-supplied window 
procedures are located in a Presentation Manager dynamic-link library 
and perform minimal default processing in response to messages sent 
to the window. 

Although the system window procedures associated with pre¬ 
registered window classes are suitable for many types of windows, you 
should supply your own procedure for the client window. The client 
window, as you will see under step 4, is the primary window used for 
displaying program data, which is a job that must be performed by 
your own window procedure in response to the messages it receives. 
Accordingly, you must write a window procedure (WndProc in the ex¬ 
ample program, listed in Figure 2.16) and call WinRegisterClass to 
register a window class that is associated with this procedure (you pass 
the address of the procedure as one of the parameters). As you will soon 
see, when you subsequently create the client window, you can make it 
an instance of this class; accordingly, all messages sent to this window 
will cause your procedure to receive control. 

Note that a given window class can have more than one instance; in 
other words, several windows can be assigned to a single window class 
when they are created. Consequently, a window procedure may have to 
process messages for multiple windows (the identity of the target win¬ 
dow is supplied as part of the message). Flowever, the window class 
created by the example program (which is associated with the window 
procedure WndProc) has only a single instance—the client window. 

At this point in the program, no windows have actually been created. 
WinRegisterClass performs the following three primary functions in 
preparation for creating a window: 

1. WinRegisterClass creates a window class and assigns this class 
an arbitrary name, which is supplied through the second 
parameter. The example program chooses the name MAIN . As 
you will discover under step 4, you must supply this name when 
creating the client window to make it an instance of this class. 
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2. WinRegisterClass associates a window procedure with the class 
it creates. You specify this procedure by passing its address as 
the second parameter; subsequently, the system will invoke the 
specified procedure when it sends messages to any window 
belonging to this class. 

3. WinRegisterClass assigns a set of default styles (the third 
parameter) to the window class. You can specify one or more of 


• Table 2.1: Presentation Manager Class Styles 


Class style 

Effect 

CS_CL1PCHILDREN 

The system will exclude the area occupied by the 
window's children from the window's clipping area (the 
area in which it can paint). 

CS_CL,IPSIBLINGS 

The system will exclude the area occupied by the 
window's siblings from the window's clipping area. 

CS_MOVENOTIFY 

The system will generate a WM_MOVE message 
whenever the window is moved on the screen. 

CS_PARENTCLIP 

The system will extend the window's clipping area to 
encompass the area of its parent. 

CS_PUBLIC 

The system will register a public window class; this style 
can be specified only by the shell process. 

CS_SAVEBITS 

The system will save the screen area under the window 
when it is made visible; when the window is removed, 
the system will restore the area it occupied without 
sending a WM_PAINT message. 

CS_SIZEREDRAW 

The system will invalidate the entire window and 
generate a WM_PAINT message (forcing the window 
procedure to recreate screen data) whenever the window 
is reduced or enlarged in size. 

CS_SYNCPAINT 

The system will send a WM_PAINT message directly to 
the window procedure whenever any section of the 
corresponding window becomes invalid (as opposed to 


merely posting the message to the message queue). 
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the styles listed in Table 2.1. These styles are identified with con¬ 
stants (defined in an OS/2 header file) that have the CS_ (class 
style) prefix; if you want more than one style, you must combine 
the identifiers with the bitwise OR operator (I). The example 
program does not require any styles, and therefore passes a 
value of 0. If, however, you select one or more styles, all win¬ 
dows subsequently created with this class will automatically ac¬ 
quire the chosen style (in addition to any styles specified when 
creating the window). 


Step 4: Create a Window 

The function main is now ready to create a window. A Presenta¬ 
tion Manager window is a highly significant entity; it is not only the 
main vehicle for interacting with the program user, but, as you will 
soon discover, it is the program object that receives all messages. 

The program creates a standard window by invoking the function 
WinCreateStdWindow (Figure 2.5). Calling this function is the easiest 
way to create a general-purpose main program window that has such 
features as a title bar and a system menu. When you call WinCreateStd¬ 
Window, you request the specific features required. Each of these fea¬ 
tures is actually a distinct window (known as control windows ); thus, the 
standard "window" created by WinCreateStdWindow typically con¬ 
sists not of a single window but of a family of related windows. 

The function WinCreateStdWindow creates at least one primary 
window known as the frame window. The frame window has no visible 
distinguishing characteristics; however, all of the other windows 
created by WinCreateStdWindow, such as the title bar, the sizing bor¬ 
der, and the client area, add visible features and are placed within the 
area occupied by the frame window. The frame window is the parent of 
these other windows. Presentation Manager windows are organized in 
parent-child relationships, and a child window is always displayed 
within the area occupied by its parent and overlaps its parent (if a por¬ 
tion of a child window is moved beyond the bounds of its parent, that 
portion is clipped , or made invisible). Note that all child windows are 
automatically moved, minimized, hidden, or destroyed together with 
their parent window. Note also that a child window can overlap 



WinCreateStdWindow 

Purpose: 

Creates a standard window. 


Prototype: 


HWND APIENTRY WinCreateStdWindow 


(HWND hwndParent, 


ULONG flStyle, 


PVOID pCtlData, 


PSZ pszClientClass, 


PSZ pszTitle, 


The handle of the parent window; the 
value HWND_DESKTOP indicates 
that the parent is the Presentation 
Manager desktop, which results in a 
main (top-level) window; the value 
HWNDOBJECT creates an object 
window (which has no parent). 

Frame window style; can be a 
combination of the window styles 
(WS_) listed in Table 2.2 or the frame 
styles (FS_) listed in Table 2.3. 

Pointer to a ULONG variable that has 
been assigned a combination of 
window control styles, which have the 
FCF_ prefix and are listed in Table 2.4. 
These styles specify the control 
windows that should be included, and 
are combined with the bitwise OR 
operator. 

Pointer to a string containing the class 
name for the client window; this value 
should either be the same as the class 
name string that was passed to 
WinRegisterClass, or the value 
NULL; if the value is NULL, the 
system will not create a client window. 
Pointer to a string containing the text 
to be displayed in the title bar; this 
parameter is ignored if there is no title 
bar (that is, FS_TITLEBAR is not 
specified in flStyle). 


Figure 2.5: 

The WinCreateStdWindow Presentation Manager function 
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ulong styleClient , Style of client window; can be a 

combination of the window styles 
(WS_) listed in Table 2.2; this 
parameter is ignored if there is no 
client window (that is, pszClientClass 
is NULL). 

hmodule hmod, Resource module handle (applies only 

if flStyle includes one or more of 
FSJCON, FS_ACCELTABLE, or 
FS_MENU); if the resources are 
contained in a dynamic-link module, 
this parameter should be the module 
handle returned by DosLoadModule; 
otherwise, it should be NULL, 
indicating that the resources are 
contained in the .EXE file. 

ushort idResources, Frame window identifier and 

identifier of any resources that are 
used (applies only if flStyle includes 
one or more of FS_ICON, 
FS_ACCELTABLE, or FS_MENU); all 
resources used by one standard 
window must be assigned the same ID 
in the resource script file. 

PHWND phwndClient) ; Pointer to variable to receive the 

handle for the client window. 

Return Value: 

The frame window handle or NULL if the function is 

unsuccessful. 

Related Function: 

WinRegisterClass (Figure 2.4) 

• Figure 2.5: 

The WinCreateStdWindow Presentation Manager function (continued) 
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another child window (known as its sibling ), but a parent window can¬ 
not overlap its child. 

The first parameter passed to WinCreateStdWindow (hwndParent) 
is the handle of the parent of the frame window. The example program 
passes the value HWNDDESKTOP, which is the handle of the desktop 
window, or the entire Presentation Manager screen. Since its parent is 
the desktop window, the frame window can be placed anywhere on the 
screen; such a window is known as a main or top-level window. Win¬ 
CreateStdWindow returns the handle of the frame window, which is 
stored in the variable HFrame. 

The second parameter (flStyle) specifies the style of the frame win¬ 
dow. This parameter can be assigned any of the window styles (which 
have the WS_ prefix) or frame styles (which have the FS_ prefix); these 
styles are combined with the bitwise OR operator (I). The win¬ 
dow styles apply to windows in general and are described in Table 2.2. 
The frame styles apply specifically to frame windows and are described 
in Table 2.3. 

The example program specifies a single window style, WS_VISIBLE, 
which causes the frame window and all its children to be immediately 
visible. When you specify WS_VISIBLE, the frame window is given an 
initial size and position on the screen that is assigned by the Presentation 
Manager shell. If you do not select the WS_VISIBLE style, the frame win¬ 
dow and its children are initially invisible. In this case, you can sub¬ 
sequently render these windows visible by calling WinShowWindow. 

The example program does not specify any of the frame styles (FS_) 
in the second parameter. As you will see in later chapters, two of the 
values that can be passed in this parameter (FS_ACCELTABLE, ex¬ 
plained in Chapter 7, and FS_ICON, explained in Chapter 10) do not 
directly affect the frame style, but rather cause the system to load 
specific resources when the window is created. 

The third parameter (pCtlData) supplies the address of a ULONG 
variable that specifies the control windows that are to be included in the 
standard window collection (such as a title bar or a system menu). This 
variable can be assigned any of the styles listed in Table 2.4 (the con¬ 
stants for these styles have the FCF_ prefix). Note that the FCF_ styles 
include not only a set of control windows, but also all of the styles that 
can be specified through the second parameter. For example, you can 
cause the system to load an icon either by assigning FS_ICON to the 
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® Table 2.2: Presentation Manager Window Styles 


Window Style 

Effect 

WS_CLIPCHILDREN 

The system will exclude the area occupied by the 
window's children from the window's clipping area (the 
area in which it can paint). 

WS_CLIPSIBLINGS 

The system will exclude the area occupied by the 
window's siblings from the window's clipping area. 

WS_DISABLED 

The window is initially disabled, meaning that it cannot 
receive mouse input; it can subsequently be enabled by 
calling WinEnableWindow. 

WS_GROUP 

The window is part of a group (applies only to dialog box 
control windows). 

WS_MAXIMIZED 

The frame window will initially be maximized. 

WS_MINIMIZED 

The frame window will initially be minimized (displayed 
as an icon). 

WS_PARENTCLIP 

The system will extend the window's clipping area to 
encompass the area of its parent. 

WS_SAVEBITS 

The system will save the screen area under the window 
when it is made visible; when the window is removed, 
the system will restore the area it occupied without 
sending a WM_PAINT message. 

WS_SYNCPAINT 

The system will send a WM_PAINT message directly to 
the window procedure whenever any section of the 
corresponding window becomes invalid (as opposed to 
merely posting the message to the message queue). 

WS_TABSTOP 

The window is among those that receive control in 


sequence as the user presses the Tab key (applies only to 
dialog box control windows). 

WS_VISIBLE 

The window is initially visible (the default is for the 


window to be initially invisible). 
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• Table 23: Presentation Manager Frame Styles 


Frame Style 

Effect 

FS_ACCELTABLE 

The system will load an 
accelerator table. 

FS_BORDER 

Frame window is given a 
narrow border. 

FS_DLGBORDER 

Frame window is given a 
standard dialog box border. 

FS_ICON 

The system will load an icon 
and display it when the 
window is minimized (see 


Chapter 10). 

FS_NOMOVEWITHOWNER 

Do not move the window with 
its owner. 

FS_SHELLPOSITION 

Window is assigned a default 
size and position on the screen 
and is initially visible. 

FS_SIZEBORDER 

Includes a wide sizing border 
window. 

FS_STANDARD 

Equivalent to 

(FS_ACCELTABLE IFS_ICON 

1 FS_SHELLPOSITION 1 
FS_TASKLIST). 

FS_SYSMODAL 

The window is system modal, 
meaning that it retains the focus 
until it is destroyed; this 
prevents the user from 
switching away from the 
window while it maintains 
control. 

FS_TASKLIST 

The program will be listed 
within the Task Manager 
window. 
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® Table 2A: Presentation Manager Control Window Styles 

Frame Style Control Window Included/Style Effect 

FCFACCELTABLE The system will load an accelerator table from the 

resource file specified in the hmod parameter to 
WinCreateStdWindow. 

Frame window is given a narrow border. 

Frame window is given a standard dialog box border. 
Horizontal scroll bar. 

The system will load an icon and display it when 
the window is minimized (see Chapter 10). 

Application menu. 

Maximize box. 

Minimize box. 

Minimize/maximize box. 

Do not move the window with its owner. 

Window is assigned a default size and position on 
the screen and is initially visible. 

Wide sizing border. 

Equivalent to (FCF_ACCELTABLE I FCFJCON I 
FCF_MENU I FCF_MINMAX I 
FCF_SHELLPOSITION I FCF_SYSMENU I 
FCF_SIZEBORDER I FCF_TASKLIST I 
FCF_TITLEB AR). 

FCF_SYSMENU System menu. 

FCF_SYSMODAL The window is system modal , meaning that it 

retains the focus until it is destroyed; this prevents 
the user from switching away from the window 
while it maintains control. 

ECEJTASKLIST The program will be listed within the Task 

Manager window. 

FCFJTITLEBAR Title bar. 

FCF VERTSCROLL Vertical scroll bar. 


FCFBORDER 

FCF_DLGBORDER 

FCFHORZSCROLL 

FCFJCON 

FCFJMENU 

FCFJMAXBUTTON 

FCFJVflNBUTTON 

FCFJVIINMAX 

FCF_NOMOVEWITHOWNER 

FCF_SHELLPOSITION 

FCF_SIZEBORDER 

FCF_STANDARD 
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second parameter, or by assigning FCF ICON to the variable pointed to 
by the third parameter. (The set of styles that can be assigned to the 
second parameter using the FS_ constants are thus a proper subset of 
the styles that can be assigned through the third parameter using the 
FCF_ styles. The reason for this redundancy is unclear; however, for 
the duplicated styles, you have a choice of which parameter you want 
to use to specify them.) 

The example program specifies the following control window styles 
(which are assigned to the ULONG variable CtiData; the address of 
CtlData is passed to WinCreateStdWindow): 

• FCF_MINMAX, which includes a minimize/maximize box win¬ 
dow. This box allows you to reduce the window to an icon on 
the screen, or to expand the window to encompass the entire 
screen. These actions are performed by clicking the mouse over 
the appropriate icon, or through the system menu. 

• FCF_SHELLPOSITION, which causes the system to assign the 
window an initial size and position on the screen, making it im¬ 
mediately visible. If you do not include this value, the window 
will be created with zero dimensions, and will thus be invisible 
on the screen until the program calls WinSetWindowPos to ex¬ 
plicitly assign the window dimensions and position. 

• FCF_SIZEBORDER, which incorporates a wide sizing border 
window that you can use to change the size of the frame win¬ 
dow with the mouse; if you include this window, you can also 
change the size through the system menu. Note that if you do 
not request creation of a sizing border window, you can give the 
frame window a simple border (by assigning the third 
parameter the value FCF_BORDER for a thin border or 
FCF_DLGBORDER for a wide border, or by assigning the 
equivalent FS_ style to the second parameter). These simple bor¬ 
ders enhance the appearance of the frame window, but do not 
allow resizing the window; they are not distinct control windows. 

• FCF_SYSMENU, which includes a system menu window. The 
system menu allows you to minimize, maximize, restore, resize, 
or move the frame window, or to terminate the program. You 
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can open this window by clicking on the icon with the mouse, or 
by pressing the Alt-Spacebar key combination. 

® FCF_TASKLIST, which lists the program within the Task 

Manager window, allowing the user to switch to the window 
or to terminate the program. 

® FCF_TITLEBAR, which adds a title bar window at the top of the 
frame window that displays the text specified by the fifth 
parameter (pszTitle). This control window becomes highlighted 
when the frame window is active, and can also be used to move 
the window with the mouse (you can additionally move the win¬ 
dow through the system menu). 

Note that the styles FCF_MINMAX, FCF_SIZEBORDER, FCF_SYS- 
MENU, and FCF_TITLEBAR each add a visible feature to the standard 
window that can be acted upon with the mouse to perform a specific 
action; including each of these styles also enables the corresponding ac¬ 
tion choice within the system menu (provided that the FCF_SYSMENU 
option is also specified). Therefore, for example, if you do not specify 
the FCF_SIZEBORDER style, the sizing option will be disabled within 
the system menu. 

So far, you can see that the call to WinCreateStdWindow creates five 
windows: the top-level frame window, and the four child control win¬ 
dows specified by the second parameter. This function call, however, 
creates one additional child window, the client window, which is 
specified through the fourth, sixth, and ninth parameters. The client 
window is very important; it occupies the open area inside the other 
child windows, and it is the window in which a program normally dis¬ 
plays its data. This window is also the only one for which the example 
program supplies a window procedure. All the other windows created 
by WinCreateStdWindow use the default system window procedures, 
and therefore operate somewhat autonomously; the example program, 
however, takes an active role in managing the client window. 

The fourth parameter (pszClientClass) specifies the name of the 
client window class. The example program passes the same string, 
"MAIN", that was passed to WinRegisterClass. Remember that the call 
to WinRegisterClass associated the class name "MAIN" with the win¬ 
dow procedure WndProc; passing this same string to WinCreateStd¬ 
Window causes the Presentation Manager to pass all messages sent to 
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the client window to the procedure WndProc. If a program assigns the 
fourth parameter a value of NULL, no client window is created. 

The sixth parameter (styieClient) sets the style of the client window, 
and can be any of the WS_ window styles listed in Table 2.2. The ex¬ 
ample program accepts the default styles by passing a value of 0 (unlike 
the frame window, the client window is made visible by default). The 
ninth parameter (phwndClient) is the address of the variable that is to 
receive the client window handle; the program passes the address of the 
local variable HClient. Note that parameters 6 and 9 are ignored if the 
fourth parameter is NULL (causing no client window to be created). 

The fifth parameter (pszTitle) supplies the text that is displayed 
within the title bar. Note that the system prefixes the name of the ex¬ 
ecutable file to the string you pass through this parameter. Since the 
example program passes the string 

": PM Text Editor" 

the system displays the title 

"FIG2_27.EXE: PM Text Editor" 

As you will see in Chapter 7, you can call the function WinSetWindow 
at any time to specify the exact text shown in the title bar. 

Finally, the seventh and eighth parameters provide information 
regarding the program resources that are used only if the standard win¬ 
dow includes an accelerator table, an icon, or a menu (requested as con¬ 
trol window styles through the third parameter). Since none of these 
frame styles is specified in this program, parameters seven and eight 
are assigned a value of 0. Menus, accelerator tables, and resources in 
general are discussed in Chapter 7. Chapter 10 describes icons and 
other specific resources. 

Figure 2.6 illustrates the appearance of the window created by the call 
to WinCreateStdWindow. Each of the individual windows is labeled, 
except for the frame window, which underlies the entire area and is not 
visible. Figure 2.7 illustrates the parent-child relationships of these win¬ 
dows. Note that even though the example program creates only a single 
top-level window (the frame), other Presentation Manager applications 
currently sharing the screen may also have created top-level windows; 
in the diagram, each of these is labeled Other Top-Level Window. 
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WinCreateStdWindow is a convenient function for quickly creating 
a frame window and a collection of child control windows. You can, 
however, also create individual top-level or control windows through 
the function WinCreateWindow. This function offers a finer level of 





PM Text Editor 


TITLE BAR 


MINIMIZE ICON 


SYSTEM MENU ICON 


MAXIMIZE ICON 


CLIENT AREA 


SIZING BORDER 


• Figure 2.6: 

The basic components of the window created by the example program 



• Figure 2.7: 

Genealogy of the windows created by WinCreateStdWindow 
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control over the windows it creates. Note also that a program can create 
several top-level windows, each of which could subsequently create 
one or more child windows. 


Step 5: Get and Dispatch Messages 

As stated earlier, the system sends many messages to windows to 
convey important information and to inform them of a wide variety of 
events. When the system sends a message to any of the six windows 
that belong to the example program, it places the message in the queue 
created by the call to WinCreateMsgQueue (when a given program 
thread creates a message queue, the system places messages to all 
windows created by this thread into the queue). Once the function 
main has performed necessary initializations and has created all re¬ 
quired program objects, its sole responsibility is to extract messages 
from the message queue and rapidly dispatch them. Accordingly, the 
heart of the function main of a Presentation Manager application is a 
loop that repeatedly calls WinGetMsg (Figure 2.8) to extract the next 
message from the queue, and then calls WinDispatchMsg (Figure 2.9) 
to dispatch this message through the system so that the message can be 
processed. 

The function WinGetMsg extracts the next available message from 
the queue, waiting if necessary until a message is available. In general, 
WinGetMsg supplies messages in the same order in which they were 
inserted into the queue (by the system or by an application); the system, 
however, may alter the queue position of certain messages that have a 
special priority level (for example, the WM_PAINT message, described 
later in the chapter, is given a low priority, and is supplied only after all 
other messages waiting in the queue have been extracted). The call to 
WinGetMsg in the example program simply removes the next message, 
although, as indicated in Figure 2.8, by setting the last three parameters 
you can also extract messages belonging to specific windows, or mes¬ 
sages within a particular range of message identifiers. (Note that you 
can call WinPeekMsg to examine queue messages without removing 
them.) When WinGetMsg is called, the system copies the contents of 
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WinGetMsg 

Purpose: 


Extracts the next message from the message queue belong¬ 
ing to the current thread. 

Prototype: 

BOOL APIENTRY WinGetMsg 

(HAB hab, 

Anchor block handle. 

PQMSG pqmsg, 

Pointer to a QMSG structure 
that is to be assigned the 
content of the message; see the 
text for a description of this 
structure. 

HWND hwndFilter, 

The "window filter"; if this 
parameter contains a window 
handle, only a message for that 
window will be obtained; if it 
is assigned NULL, the next 
message for any window is 
extracted. 

USHORT msgFilterFirst, 

The ID of the first message of 
the desired range of messages; 
if this parameter and 
msgFilterLast are both 0, then 
there is no range constraint, 
and the next message will be 
extracted without regard to its 

ID. 

USHORT msgFilterLast); 

The ID of the last message of 
the desired range, or 0 if there 
is no range constraint. 


• Figure 2.8: 

The WinGetMsg Presentation Manager function 
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Return Value: 

TRUE, unless the message is WM_QUIT, which causes the 
function to return FALSE. 

Notes: 

This function waits, if necessary, until a message that satis¬ 
fies the specified criteria (if any) is available. It extracts the 
next available message, unless the second parameter speci¬ 
fies a particular window, or the third and fourth parameters 
indicate a restricted range of message identifiers. 

Related Function: 

WinDispatchMsg (Figure 2.9) 


• Figure 2.8: 

The WinGetMsg Presentation Manager function (continued) 

the extracted message into the QMSG structure, the address of which is 
passed as the second parameter. This structure is defined as follows: 


typedef struct __QMSG 

{ 

HWND hwnd; /* Handle of the window to which the */ 
/* message is addressed. */ 

USHORT msg;/* The message identifier. */ 

MPARAM mpl;/* Message-specific information. */ 

MPARAM mp2;/* More message-specific information. */ 
ULONG time;/* Time message was posted to queue. */ 
POINTL ptl;/* Position of mouse when message was */ 
/* posted to queue. */ 

} 

QMSG; 
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The first field of this structure identifies the particular window to 
which the message is sent. The next three fields contain the actual con¬ 
tent of the message. The field msg is the message identifier; for ex¬ 
ample, the message with the identifier WM_PAINT is sent to the client 
window whenever this window must redisplay a portion of its data. 
The third and fourth fields (mpl and mp2) provide 8 bytes of additional 
message information. The meaning of these fields depends upon the 
specific message; for example, the WM_CHAR message, sent when 
the user presses a key, places the hardware scan code and other infor¬ 
mation in mpl and the character codes in mp2. Versions of the example 
program given in later chapters handle a wide variety of messages. 


WinDispatchMsg 

Purpose: 

Causes the system to call a window procedure. 

Prototype: 

ULONG APIENTRY WinDispatchMsg 

(has hab, Anchor block handle. 

pqmsg pqmsg) ; Pointer to a QMSG message queue structure; 

information from this structure is passed to 
the window procedure; see the text for a 
description of this structure. 

Return Value: 

The value returned by the window procedure that is called. 
Notes: 

This function is equivalent to calling WinSendMsg, with 
parameters corresponding to the appropriate fields in the 
QMSG structure. 

Related Functions: 

WinGetMsg (Figure 2.8) 

WinSendMsg (Figure 4.8) 


@ Figure 2.9: 

The WinDispatchMsg Presentation Manager function 
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Once the call to WinGetMsg has extracted a message from the queue, 
the example program immediately gives this message back to the sys¬ 
tem by calling WinDispatchMsg, passing the address of the structure 
containing the message. WinGetMsg normally returns a value of 
TRUE; if, however the extracted message has the identifier WM_QUIT, 
then WinGetMsg returns FALSE, which causes termination of the mes¬ 
sage loop. Thus, WM_QUIT is the only message that is not immediately 
dispatched, but rather serves to end the program. In the example pro¬ 
gram, the system places this message in the queue when the user selects 
the Close option from the system menu. The WM QUIT message is 
described in Figure 2.10. 

It might seem that by immediately calling WinDispatchMsg, the 
program relinquishes its opportunity to act upon relevant messages; 


WM__QUIT 

Purpose: 

This message is posted to the message queue to terminate 
the application. 

Parameters: 

mparam mpl Reserved; must be NULL. 

mparam mp2 Reserved; must be NULL. 

Return Value: 

Not applicable (message is not processed by a window 
procedure). 

Notes: 

This message causes WinGetMsg to return FALSE (this 
function normally extracts a message from the queue and 
returns TRUE). A FALSE return value is a signal that the pro¬ 
gram should end; this message, therefore, would typically 
never be passed to a window procedure. 


® Figure 2.10: 

The WM_QUIT Presentation Manager message 
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however, there will be another opportunity to process certain messages. 
WinDispatdiMsg causes the system to call the window procedure as¬ 
sociated the window to which the message is addressed. The system 
can easily determine the target window, since the handle for this win¬ 
dow is the first field of the message structure. When the system calls the 
procedure associated with this window, it passes the first four fields of 
the message structure as parameters. Thus, all window procedures 
receive the parameters 

HWND hwnd; 

USHORT msg; 

MPARAM mpl; 

MPARAM mp2; 

with the meanings described above. Each message that is encountered 
in the course of developing the example program presented in this book 
will be explained in an accompanying figure (such as WM QUIT in Fig¬ 
ure 2.10). These figures explain the content of the two parameters, mpl 
and mp2, that are passed to the window procedure, as well as the value 
that is returned from the window procedure. 

In the example program, WinDispatdiMsg causes the system to call 
a predefined system procedure for messages sent to any window except 
the client window. There is a specific predefined procedure for each 
type of window; these procedures perform a minimal default action in 
response to the message. The predefined window procedure for a 
specific control window creates the appearance of the window and 
determines the manner in which the window functions. For example, 
the window procedure associated with the minimize/maximize box 
draws the arrows and causes the frame window to be maximized when 
the user clicks on the up-arrow. After the window procedure returns, 
control passes back to the function main, which proceeds to extract the 
next message. 

If, however, the message is sent to the client window, the system calls 
the function WndProc (contained within the example program and 
listed in Figure 2.16) rather than a predefined window procedure. The 
system knows to call WndProc, because when the client window was 
created in the call to WinCreateStdWindow, the program passed the 
class name "MAIN", which was associated with the procedure WndProc 
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in the previous call to WinRegisterClass. Figure 2.11 reviews the se¬ 
quence of associations that allows the example program to install its 
own procedure for the client window. How WndProc processes the 
messages it receives is discussed later in the chapter. 



EFFECT 


Address of WndProc 
is associated 

with the class name "MAIN" 


Class name "MAIN" is associated 
with client window handle 


System calls WndProc, 
passing contents of message 
as parameters 


• Figure 2.11: 

Steps for implementing the window procedure 
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Note that WinDispatchMsg is a synchronous function, meaning that it 
does not return control to the calling program until the window proce¬ 
dure it invokes has returned. Thus, messages are normally handled 
serially and in the order they have been placed in the queue. However, 
as mentioned later in this chapter and fully explained in Chapter 12, a 
given window procedure can start a secondary thread to execute 
a lengthy task, and return control immediately to the system. Win¬ 
DispatchMsg returns whatever value was returned by the window pro¬ 
cedure; the example program ignores this value. 

The description of message handling given so far has been over¬ 
simplified; there are two additional considerations. First, the system is 
not the only source of messages. An application can also send a message 
to a given window; a window procedure can even send a message to 
itself (this technique greatly simplifies coding of these procedures, and 
you will see many examples later in the book). Second, not all messages 
are placed in the message queue; when certain messages are sent to a 
window, the system calls the window procedure immediately, circum¬ 
venting both the message queue and the message-handling loop in the 
function main. Figure 2.12 provides an overview of the Presentation 
Manager message-handling mechanism. 

You can now see that the expression "sending a message to a win¬ 
dow" simply means calling the window procedure associated with the 
window, passing the contents of the message as parameters (whether or 
not the message passes through a queue). Messages are so central to 
Presentation Manager applications that these programs are said to have 
a message-based architecture. Sending messages is the primary means for 
exchanging information and transferring program control, and receiv¬ 
ing messages is the central activity of the main procedure. The primary 
thread of control of a Presentation Manager application thus spends its 
time waiting until it receives a message, and then handling the message 
appropriately. In contrast, a conventional program actively initiates ac¬ 
tivities at predefined points in its sequence of instructions. A Presenta¬ 
tion Manager program is thus more reactive, and a conventional 
program is more proactive. The more passive stance of a Presentation 
Manager application makes sense in an environment where basic 
resources are intimately shared (specifically, the screen, keyboard, and 
mouse), and where the user is given the privilege of manipulating the 
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program window at almost any time. A Presentation Manager applica¬ 
tion must be highly responsive to the demands of its environment. 


Step 6: Release 

Presentation Manager Resources 

When the function WinGetMsg in the example program extracts 
the message WM QUIT from the queue, it returns a value of FALSE, 
and the while loop terminates. Before exiting, the program releases the 
resources it has acquired from the Presentation Manager. First it calls 
WinDestroyWindow (Figure 2.13) to dispose of the frame window and 



PRESENTATION 


MESSAGE MANAGER 

SOURCE APPLICATION 


*> Figure 2.12: 

The Presentation Manager message-handling mechanism 
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all its children, then it calls WinDestroyMsgQueue (Figure 2.14) to free 
the message queue, and finally it calls WinTerminate (Figure 2.15) to 
sever its final ties with the Presentation Manager. If a program ter¬ 
minates without calling these functions, the Presentation Manager 
automatically releases its resources. Thus, these function calls are not 
absolutely necessary; including them, however, may give the program a 
more orderly appearance as it terminates and removes various objects 
from the screen. 


• PROCESSING MESSAGES 

As explained in the previous section, the system calls the proce¬ 
dure associated with a particular window whenever a message is sent 


WinDestroy Window 

Ptujfose: 

Destroys the specified window and all its descendant win¬ 
dows. 

Prototype: 

BOOL APIENTRY WinDestroyWindow 
(hwnd hwnd) ; Handle of window to destroy. 

Return Value: 

TRUE if the function was successful, FALSE otherwise. 
Notes: 

The window must have been created by the same thread that 
calls this function. When a window is destroyed, the 
WM_DESTROY message is sent to the window. 


® Figure 2.13: 

The WinDestroyWindow Presentation Manager function 




Creating a Window 5 9 




to this window. Therefore, all messages sent to the client window cause 
the system to call the function WndProc, which is part of the example 
program and is listed in Figure 2.16. 

The window procedure must test the second parameter (msg) to 
determine the identity of the message, and branch to the appropri¬ 
ate section of code to handle this message. This action is most easily 
accomplished with a switch statement. When the window procedure 
has completed processing the message, it should return a value of either 
TRUE or FALSE, depending upon the particular message. The window 
procedure does not have to process all messages; it can select certain 
messages to handle and then pass all other messages to the system for 
default processing by calling WinDefWindowProc (Figure 2.17). 

The function WndProc processes only the WM_PAINT message and 
lets the system worry about all other messages by passing them to Win¬ 
DefWindowProc. The WM_PAINT message is sent to the client window 


WinDestroyMsgQueue 

Purpose: 

Destroys the specified message queue. 

Prototype: 

BOOL APIENTRY WinDestroyMsgQueue 
(hmq hmq) ; The handle of the message queue to be 

destroyed. 

Return Value: 

TRUE if the function was successful, and FALSE otherwise. 
Notes: 

This function is normally called after destroying all program 
windows, but before calling WinTerminate, in preparation 
for program exit. 

• Figure 2.14: 

The WinDestroyMsgQueue Presentation Manager function 
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procedure whenever a section of this window needs repainting (that is, 
after all or a portion of its data have been destroyed). The actual work of 
repainting the window is accomplished by the function Paint, which is 
also part of the example program and is explained in the next section. 

Note that the window procedure must return before any other mes¬ 
sages waiting in the queue can be extracted and processed. The window 
procedure should therefore perform its task rapidly and then return con¬ 
trol. Chapter 12 discusses how to start a secondary thread to allow the 
window procedure to perform a lengthy task, yet return control quickly. 


WinTerminate 

Purpose: 

Signals the Presentation Manager that the calling thread has 
finished using the services of the Presentation Manager, and 
releases all Presentation Manager resources held by this 
thread. 

Prototype: 

BOOL APIENTRY WinTerminate 

(hab hab) ; The anchor block handle held by the current 

thread. 

Return Value: 

TRUE if the function is successful, FALSE otherwise. 

Notes: 

This function is normally called immediately before the pro¬ 
gram terminates, after it has completed calling all other 
Presentation Manager functions. 


• Figure 2.15: 

The WinTerminate Presentation Manager function 
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DISPLAYING DATA 
• WITHIN THE WINDOW 

The client window procedure in the example program calls the 
function Paint whenever it receives the WM_PAINT message. This func¬ 
tion, listed in Figure 2.18, serves to update the data displayed within the 
program's client window. Specifically, the function clears the entire area 
within the window and prints a string at the upper left corner. 


When the WM_PAINT Message Is Sent 

Before describing the steps required to draw data within a window, it 
is important to understand when the function Paint is called (that is, the 
circumstances under which the system sends the WM_PAINT message). 
First, the system automatically sends the WM_PAINT message when the 
window is first created during the execution of the WinCreateStdWindow 
function. This gives the program an opportunity to create its initial screen 
display. The WM_PAINT message is described in Figure 2.19. 


MRESULT EXPENTRY WndProc 

(HWND hwnd, /* Window handle. */ 

USHORT msg, /* The message. */ 

MPARAM mpl, /* Message-specific information. */ 

MPARAM mp2) /* Message-specific information. */ 

{ 

switch (msg) 

case WM_PAINT: /* Process window paint message. */ 


return Paint (hwnd, msg, mpl, mp2); 
default: /* Perform the default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} 

} /* end WndProc */ 


• Figure 2.16: 

The function WndProc of the example program 
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Second, the system sends WM_PAINT whenever the entire window, 
or any portion of it, becomes invalid. An invalid area of a window is a 
section that needs to be displayed, but for which screen data are not 
available; it is therefore a section of the window that requires updating. 
For example, when the user increases the size of a window (by resizing, 
maximizing, or restoring it from an icon), the system does not have data 
for the newly uncovered area and therefore issues a WM_PAINT mes¬ 
sage to force the client window procedure to update the display Also, if 
another window is placed on top of the client window, the system does 
not normally save the overwritten data; therefore, when the overlying 
window is removed, the system sends the client window a WM_PAINT 


WinOefWindowProc 

Purpose: 

Passes a message to the system for default processing. 
Prototype: 

MRESULT APIENTRY WinDefWindowProc 
(hwnd hwnd, Handle of the window to which the message 

was originally sent. 
ushort msg, Message identifier. 

mparam mpi , Message parameter 1. 

mparam mp2) ; Message parameter 2. 

Return Value: 

The return value depends upon the specific message. 

Notes 

A window procedure normally calls this function to handle 
messages that it does not want to process itself. The window 
procedure should pass this function the same parameters that 
it received when it was invoked. 

• Figure 2.17: 

The WinDefWindowProc Presentation Manager function 
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message. (If, however, the overlying window was created with either 
the CS_SAVEBITS or the WS_SAVEBITS style, the system will automat¬ 
ically save and restore the overwritten data, and will not need to send a 
WM_FAINT message.) Note that when the window is moved, the sys¬ 
tem directly transfers the data without sending WM_PAINT. 


MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

HPS HPresSpace; /* Presentation space handle. */ 

RECTL Rect; /* Window rectangle, in window coordinates. */ 

static char Message [] = /* Text to display. */ 

"This line is displayed by the window procedure."; 

/*** Obtain a handle to a presentation space. ********************************/ 

HPresSpace = WinBeginPaint /* Returns presentation space handle. */ 

(hwnd, /* Window handle. */ 

0, /* 0 requests a cache presentation space. */ 

0); /* Address of variable to set to update region: none. */ 

/*** Obtain the coordinates of the client window. ****************************/ 


WinQueryWindowRect 

(hwnd, /* Window handle. */ 

&Rect); /* Structure to receive coordinates. */ 

/*** Erase the existing contents of the screen. ******************************/ 

WinFillRect /* Draws a filled rectangular area. */ 

(HPresSpace, /* Presentation space handle. */ 

&Rect, /* Structure containing window coordinates. */ 

CLR_WHITE); /* Color to use (white). */ 


/*** print the line of text. ************************************************/ 


WinDrawText /* Draws a single line of formatted text into a rectangle. */ 
(HPresSpace, /* Presentation space handle. */ 

Oxffff, /* Length of string: Oxffff means 0 terminated.*/ 

Message, /* Text to be displayed. */ 

&Rect, /* Coordinates of rectangle containing text. */ 

CLR_BLACK, /* Foreground color. */ 

CLR_WHITE, /* Background color. */ 

/* Drawing specifications: */ 

DT_LEFT | /* Left justify. */ 

DT_T0P); /* Place at top of window. */ 

/*** Release presentation space / revalidate window. *************************/ 

WinEndPaint (HPresSpace); /* Tells Presentation Manager that */ 

/* redrawing is complete. */ 

return FALSE; 


) /* end Paint */ 

© Figure 2.18: 

The function Paint of the example program 
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In general, a Presentation Manager program needs to write data to 
the window under two circumstances. First, it must update the window 
display in response to external events, such as the user enlarging the 
window. In this case, the system automatically sends a WMJPAINT 
message. Second, the program must create an initial screen display and 
update this display whenever there is a change in the program's visible 
data (for example, the client window of a text editor must be updated 
whenever the user enters a new character into the file). As you have 
seen, the system automatically issues a WM_PAINT message at win¬ 
dow initialization to allow drawing the opening window display. Also, 
as you will see later in the book, you can trick the system into sending a 
WM_PAINT message at any time by explicitly invalidating sections of 


WM_PAINT 

Purpose: 

This message is sent by the system to a window whenever 
the entire window, or any portion of it, needs redrawing. 

Parameters: 

mparam mpl NULL (Reserved value). 

mparam mp2 NULL (Reserved value). 

Return Value: 

NULL. 

Notes: 

When this message is received, the window procedure must 
explicitly draw the data within the invalid section of the win¬ 
dow. The function WinBeginPaint (Figure 2.20) supplies the 
coordinates of the invalid region, and WinEndPaint (Figure 
2.21) informs the Presentation Manager that the window is 
now completely valid. 


• Figure 2.19: 

The. WMJPAINT Presentation Manager message 
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the screen. Therefore, all window output can be handled through the 
section of the window procedure that responds to the WM JPAINT mes¬ 
sage. Accordingly, you can centralize all screen-drawing code within a 
single all-purpose function (in this example, the function Paint), and 
you do not need to have drawing functions scattered throughout the 
program. This is a fortunate design feature, since, as you will see in the 
next section, drawing within a window is not a trivial task. 


Steps for Updating the Screen 

Although the function Paint merely clears the window and dis¬ 
plays a single string, it serves to illustrate the essential steps required to 
update a window display under the Presentation Manager. 

Before writing to the window, the function Paint calls WinBegin- 
Paint (Figure 2.20); after it has completed updating the display, it calls 
WinEndPaint (Figure 2.21). These two functions must surround all 
other functions that generate output to the window, and they serve two 
primary purposes. First, as mentioned in the previous section, the 
WM_PAINT message is sent whenever a section of the window is in¬ 
valid. Calling the functions WinBeginPaint and WinEndPaint signals 
the system that you are updating the window display and that the win¬ 
dow therefore no longer contains an invalid region; in other words, 
these functions reset the invalid area to NULL. 

Second, WinBeginPaint provides a handle to a presentation space. 
Under the Presentation Manager, you do not draw directly onto a 
physical device, such as the screen or a printer. Rather, you draw onto 
an abstract surface known as a presentation space. A presentation space 
is implemented as a data structure within the Presentation Manager, 
and it has a set of characteristics that are independent of any physical 
device, such as a current font and current drawing colors. Before you 
can produce output, however, you must associate the presentation 
space with a physical device, known as the device context. The Presenta¬ 
tion Manager provides several functions for creating presentation 
spaces and associating them with device contexts; also, there are several 
different types of presentation space. 

Calling WinBeginPaint, however, is a convenient method for per¬ 
forming both steps in a single function call (that is, obtaining a presen¬ 
tation space and associating it with a device context). This function 
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WinBeginPaint 

Purpose: 

Obtains a handle to a presentation space that is associated 
with the specified window. 

Prototype: 

HPS APIENTRY WinBeginPaint 

(hwnd hwnd, Handle of the window to receive data. 

hps hps , Handle of an existing presentation 

space to be associated with the 
window given by hwnd; if this 
parameter is NULL, the system 
supplies a cache presentation space. 

prectl prciPaint ) ; Address of a RECTL structure to 

receive the window coordinates of the 
smallest rectangle bounding the 
invalid region(s) of the window; this 
structure is defined in Figure 2.22. 

Return Value: 

The handle of the presentation space. 

Notes: 

The presentation space obtained by this function is ready for 
drawing onto the specified window. Note that after this 
function is called, the system considers the window data 
completely valid (that is, the invalid region of the window is 
set to NULL). You must call WinEndPaint after the window 
has been updated. 

Related Function: 

WinEndPaint (Figure 2.21) 


• Figure 220: 

The WinBeginPaint Presentation Manager function 
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returns a handle to a presentation space that is already associated with 
a window (the window specified through the first parameter) and is 
ready to receive output. The example program passes 0 as the second 
parameter, which causes WinBeginPaint to supply a cache presentation 
space; this type of presentation space is provided from the system's in¬ 
ternal cache of presentation spaces, and it can be allocated quickly and 
without consuming additional memory. The call to WinEndPaint 
releases the presentation space after the window is updated. Note that 


WinEndPaint 

Purpose: 

Signals the system that the updating of the window (which 
occurs typically in response to a WM_PAINT message) is 
complete. 

Prototype: 

BOOL APIENTRY WinEndPaint 

(hps hps) ; Handle of presentation space that was used 

for painting the window. 

Return Value: 

TRUE if the function was successful, FALSE otherwise. 
Notes: 

After you have called WinBeginPaint and have completed 
updating the window display, you must call WinEndPaint. 
If the call to WinBeginPaint supplied a cache presentation 
space, WinEndPaint returns this presentation space to the 
cache. 

Related Functions: 

WinBeginPaint (Figure 2.20) 


• Figure 2.21: 

The WinEndPaint Presentation Manager function 
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you must call WinEndPaint before returning from processing the cur¬ 
rent message. 

Once a handle to a presentation space has been secured, the function 
Paint obtains the current dimensions of the client window by calling 
WinQueryWindowRect (Figure 2.22). This function assigns the dimen¬ 
sions to a RECTL structure (defined in Figure 2.22); note that since the 


WinQueryWindowRect 

Purpose: 

Returns the coordinates of the specified window. 

Prototype: 

BOOL APIENTRY WinQueryWindowRect 
(hwnd hwnd, Window handle, 

p rectl prclDest ); Pointer to a RECTL structure (defined 

below) to receive the coordinates of the 
window. 

Structure: 

typedef struct 
{ 


LONG 

xLe ft; 

LONG 

yBottom 

LONG 

xRight ; 

LONG 

yTop; 

} 


RECTL; 



Return Value: 

Returns TRUE if successful, and FALSE otherwise. 

Notes: 

The coordinates are given relative to the lower left corner of 
the window; thus xLeft and yBottom are both 0. 


• Figure 2.22: 

The WinQueryWindowRect Presentation Manager function 
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dimensions provided are relative to the lower left corner of the window, 
the fields xLeft and yBottom are both set to 0. The window dimensions 
are used by the two subsequent function calls. 

The function Paint next erases the former contents of the window by 
calling WinFillRect (Figure 2.23). WinFillRect draws a rectangle filled 
with a specified color; by passing the dimensions of the entire window, 
and by specifying the desired background color (white), this function ef¬ 
fectively clears the window. Note that WinFillRect is passed the handle 
to the presentation space obtained from the call to WinBeginPaint 

Once the screen has been filled with the desired background color, 
the program calls WinDrawText (Figure 2.24) to draw a string within 
the window. This function justifies a string within a specified rectangle. 
The program sets this rectangle to the dimensions of the entire screen 
and requests that the string be justified at the top and left of the rec¬ 
tangle; therefore, the string is drawn starting at the upper left corner of 
the window. WinDrawText also allows you to specify the foreground 
and background colors used to draw the string. The function call selects 
a black foreground, and it also selects a white background to match the 
background painted by WinFillRect. The window thus displays black 
letters on a white background. 


WinFillRect 

Puiyose: 

Draws a rectangle filled with a specified color. 

Prototype: 

BOOL APIENTRY WinFillRect 

(hps hps , Handle of the presentation space onto which 

the rectangle is to be drawn. 

prectl prcl , Pointer to a RECTL structure containing the 

coordinates of the rectangle to draw; see 
Figure 2.22 for the definition of this structure. 


• Figure 2.23: 

The WinFillRect Presentation Manager function 
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long icolor ) ; Color to be used to fill the rectangle; the 

following basic colors may be specified: 

CLRJ/VHITE 

clrjblack 

CLRJBLUE 

CLR_RED 

CLRJPINK 

CLR_GREEN 

CLR_CYAN 

CLR_YELLOW 

CLR_DARKGRAY 

CLR_DARKBLUE 

CLR_DARKRED 

CLR_DARKPINK 

CLR_DARKGREEN 

CLR_DARKCYAN 

clrjbrown 

CLR_LIGHTGRAY 

In addition, you can specify one of the 
following identifiers: 

Identifier Meaning 

CLRJ3ACKGROUND Default window 

color 

CLR_NEUTRAL Default 

foreground color 

Return Value: 

TRUE if the function was successful, FALSE otherwise. 


• Figure 2.23: 

The WinFillRect Presentation Manager function (continued) 


Note that the function Paint makes no attempt to determine the sec¬ 
tion of the window that is actually invalid, but rather redraws the entire 
window. Subsequent versions of the example program enhance ef¬ 
ficiency by updating only the invalid section. 
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WinDrawText 


Purpose: 

Prints a text string within a specified rectangle, using the cur- 

rent font. 

Prototype: 

SHORT APIENTRY 

WinDrawText 

(HPS hps, 

Handle of the presentation space on which 
the string is to be drawn. 

SHORT cchText, 

Number of characters contained in the 
string; the value Oxffff means that the string 
is null-terminated and the function will 
calculate its length. 

PCH pchText, 

Pointer to the string to print. 

PRECTL prcl. 

Pointer to a RECTL structure containing the 
dimensions of the rectangle inside of which 
the string is to be drawn; see Figure 2.22 for 
the definition of this structure. 

LONG clrFore, 

The foreground color; see Figure 2.23 for a 
list of colors you can specify. 

LONG clrBack, 

The background color; see Figure 2.23 for a 
list of colors you can specify. 

USHORT rgfCmd)/ 

The mode in which the string is to be drawn; 
you may assign one or more of the following 
values: 

Value Meaning 

DT_LEFT Left-justify text. 

DT_CENTER Center text. 

DT_RIGHT Right-justify text. 

DT_VCENTER Vertically center text. 

DT_TOP Top-justify text. 

DT_BOTTOM Bottom-justify text. 

Return Value: 

The actual number of characters drawn. 


• Figure 2.24: 

The WinDrawText Presentation Manager function 
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BUILDING A PRESENTATION 
• MANAGER APPLICATION 

Figures 2.25,2.26, and 2.27 (at the end of the chapter) list the three 
basic files used to build the example program: a MAKE file, a linker 
definition file, and the complete C source code file. 

The MAKE file in Figure 2.25 can be used to prepare the example pro¬ 
gram by means of the Microsoft MAKE utility. See the Microsoft 
documentation for instructions on using this utility. The C source code 
is compiled with the following command line: 

cl /W2 /c /Zp /G2ws FIG2__27 . C 
The command-line switches have the following meanings: 

Switch Meaning 

/ W2 Provides a high level of compiler warnings; the de¬ 

fault level is 1, and the highest level is 3. This flag is 
helpful for compiling any type of C program, espe¬ 
cially Presentation Manager applications, which in¬ 
volve many data types and many possibilities for 
type mismatches. 

/c Compiles without linking. The linker is invoked on a 

separate line in the MAKE file. 

/Zp Packs structures (that is, places each structure field on 
the next available byte address rather than aligning 
certain fields on even addresses); this option is impor¬ 
tant because certain OS/2 or Presentation Manager 
API functions may assume that the structures passed 
to them are packed. 

/G2 Enables instructions specific to the 80286 and later 

model processors. Since the Presentation Manager re¬ 
quires at least the 80286 processor, why not allow the 
compiler to take advantage of these more efficient 
instructions? 
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/Gw This option should be used for preparing a Presenta¬ 
tion Manager program that contains a window proce¬ 
dure; it causes the procedure to save the original 
value of the DS register on function entry, set DS to 
the appropriate value during execution of the proce¬ 
dure, and then restore the original value of DS before 
the procedure returns. These steps (referred to as the 
Window's prolog and epilog) allow a Presentation 
Manager dynamic-link module to call the window 
procedure. 

/Gs Disables the calls made to the C stack-checking 

routine at the beginning of each function; the C stack¬ 
checking routine is not compatible with the Presenta¬ 
tion Manager, since it attempts to write to the screen 
using conventional teletype-style screen output, 
which is not allowed within the Presentation 
Manager windowed environment. 

After the program is compiled, it is linked using the following command: 

link FIG2__27 .OBJ, , NUL, OS2.LIB, FIG2_26.DEF 

As mentioned in Chapter 1, OS2.LIB is the import library containing 
dynamic-link records for the OS/2 and Presentation Manager API func¬ 
tions. In addition, you may need to specify the name of the protected 
mode version of the standard C library if you have not given this library 
the standard name (SLIBCE.LIB; see your compiler documentation). 
The command also specifies the name of a linker definition file 
(FIG2_26.DEF, listed in Figure 2.26). A linker definition file contains in¬ 
formation required to prepare Presentation Manager and certain OS/2 
kernel applications. The definition file for the example program con¬ 
tains the following statements: 

Command Effect 

NAME FIG2_27 Names the application and specifies 

the program as an application rather 
than a dynamic-link module. 
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PROTMODE 


HEAPSIZE 1024 

STACKSIZE 8192 
EXPORTS WndProc 


Specifies that the program will run 
only in protected mode; including this 
statement including this statement 
may result in a small reduction in the 
program size. 

Requests a program heap of 1024 
bytes; this memory is used for 
dynamic memory allocation. 

Requests a program stack of 8192 bytes. 

Exports the window procedure so that 
it can be called by Presentation 
Manager dynamic-link modules. You 
must list all window procedures in the 
EXPORTS statement. 


Finally the complete C source code is listed in Figure 2.27. Many of the 
following chapters in this book will also list the complete set of files you 
need to build the version of the text editor presented in that chapter. These 
files are given at the end of the chapter, and consist initially of a MAKE file 
(.MAK), a linker definition file (.DEF), and a C source file (.C). Chapter 8 
will add resource files (.DLG and .RC) and a header file (.H) to this set. 


• CONCLUSION 

In this chapter, you have seen the basic sequence of function calls 
that constitute a minimal Presentation Manager application. A feature 
common to many of these function calls is the use of handles. In 
general, when a Presentation Manager function allocates an object to an 
application (such as a window), it returns a handle; this handle must be 
supplied to subsequent function calls that manipulate the same object, 
and it serves to identify the specific instance of a given type of object. 
The actual value of a handle has meaning only to the system, and not to 
the application (such variables or parameters are therefore known as 
"magic cookies"). The first handle supplied to an application is the 
anchor block handle, which is returned by Winlnitialize and identifies 
the basic set of resources and information that the Presentation 
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Manager maintains for the application. This handle must be passed to 
several other system functions. Many other Presentation Manager func¬ 
tions return additional handles; in the example program in this chapter, 
you have seen the following handles: 

® The anchor block handle 
« A message queue handle 

# Window handles for the frame and client windows 

# A presentation space handle 

Although the example program will become much larger and more 
complex in subsequent chapters, the version presented here illustrates 
most of the essential concepts involved in programming under the 
Presentation Manager. If you are accustomed to a conventional 
programming environment, some of these concepts may now seem 
somewhat alien; however, as the basic ideas are reinforced in sub¬ 
sequent chapters, you will not only become more comfortable with 
these concepts, but you will probably come to enjoy the unique and in¬ 
teresting logic of the Presentation Manager. 


# Figure 2.25 

# This MAKE file prepares the program of Figures 2.26 and 2.27 

# 

FIG2__27 . OBJ : FIG2_2 7 . C 

cl /W2 /c /Zp /G2ws FIG2_27.C 

FIG2_27.EXE : FIG2_27.0BJ FIG2_26.DEF 

'link ./NOD FIG2_27 .OBJ, , NUL, OS2.LIB SLIBCE.LIB, FIG2_26.DEF 


® Figure 2.25: 

A MAKE file for preparing the example program 


Figure 2.26 

Linker definition file for the program listed in Figure 2.27 


NAME 

PROTMODE 

HEAPSIZE 

STACKSIZE 

EXPORTS 


FIG2_2 7 

1024 

8192 

WndProc 


® Figure 2.26: 

A linker definition file for preparing the example program 
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/* 

Figure 2.27 




Version 1 of the Presentation Manager text editor example program. 



This version performs the following tasks: 



o Initializes the 

Presentation Manager system 



o Creates a message queue 
o Registers a window procedure 
o Creates a standard window 
o Processes window messages 

o Writes a line of text at the top of the window from the 



window procedure 


V 

o Relinquishes Presentation Manager resources before termination 


#include <OS2.H> 



/*** 

Declare window procedure. ***********************************************/ 

MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


void 

main () 

{ 

HAB HAncBlk; 

/* Anchor block handle. 

*/ 


HMQ HMesQue; 

/* Message queue handle. 

*/ 


HWND HFrame, HClient; 

/* Frame/client window handles. 

V 


QMSG QueMess; 

/* Message queue structure. 

V 


ULONG CtlData = 

/* Control windows to include. 

V 


FCF MINMAX 

/* Minimize/maximize box. 

V 


FCF SHELLPOSITION 

/* Make window visible on screen. 

V 


FCF SIZEBORDER 

/* Wide sizing border. 

V 


FCF SYSMENU 

/* System menu. 

*/ 


FCF TASKLIST 

/* Display program name in Task Manager. 

*/ 


FCF TITLEBAR; 

/* Title bar. 

V 

/*** 

Initialize the Presentation Manager and obtain an anchor block handle. 

**/ 


HAncBlk = Winlnitialize 

/* Returns an anchor block handle. 

V 


(0) ? 

/* Initialization options: must be 0. 

*/ 

y -k -k k 

Create a message queue for the current thread. **************************/ 


HMesQue = WinCreateMsgQueue /* Returns a message queue handle. 

*/ 


(HAncBlk 

, /* Anchor block handle. 

*/ 


o) ; 

/* Minimum queue size: 0 means default size 

• */ 

/ k k k 

Register a window procedure. ********************************************/ 


WinRegisterClass 


V 


(HAncBlk, 

/* Anchor block handle. 


"MAIN", 

/* Window class name. 

*/ 


WndProc, 

/* Window procedure associated with class. 

*/ 


0L, 

/* Class style: no styles specified. 

*/ 


o) ; 

/* Bytes of data storage for each window. 

*/ 


• Figure 2.27: 

The source codefile for the example program 
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/*** Create a standard window. ******************************************** 


HFrame = WinCreateStdWindow /* Returns handle to frame window. 


(HWND_DESKTOP / 
WS_VISIBLE, 
fcCtlData, 

"MAIN", 

M : PM Text Editor", 

CL, 

0 , 

0, 

iHClient)? 


/* Parent window handle. */ 
/* Frame window style. */ 
/* Address of control data. */ 
/* Client window class name. */ 
/* Text for title bar. */ 
/* Client window style: none specified. */ 
/* Resource module handle: none. */ 
/* Resource identification: none */ 
/* Address to receive client window hand. */ 


/*** Main message-handling loop. *********************************************/ 


while (WinGetMsg 
(HAncBlk, 
AQueMess, 

0 , 

0 , 

0 )) 


/* Get messages until WM_QUIT. 

/* Anchor block handle. 

/* Address of message structure. 
/* Window filter: any window. 

/* First message identifier: n/a. 
/* Last message identifier: n/a. 


WinDispatchMsg (HAncBlk,&QueMess); 


/* Dispatch messages. 


/*** Relinquish Presentation Manager resources and terminate application. 

WinDestroyWindow (HFrame); /* Eliminate the window. 

WinDestroyMsgQueue (HMesQue); /* Eliminate the message queue. 


WinTerminate (HAncBlk); 
} /* end main */ 


/* Sever ties with the Presentation */ 
/* Manager and release resources. */ 


/*** The window procedure and subroutines. ***********************************/ 
MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY WndProc 
(HWND hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2) 

i 

switch (msg) 

( 

case WM PAINT: 


/* Window handle. 

/* The message. 

/* Message-specific information. 
/* Message-specific information. 


/* Process window paint message. 


return Paint (hwnd, msg, mpl, mp2); 
default: /* Perform the default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2)? 


• Figure 2.27: 

The source code file for the example program (continued) 
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} /* end WndProc */ 


/*** Function for processing the window paint message. ***********************/ 

MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

HPS HPresSpace; /* Presentation space handle. */ 

RECTL Rect; /* Window rectangle, in window coordinates. */ 

static char Message [] = /* Text to display. */ 

"This line is displayed by the window procedure."; 

/*** Obtain a handle to a presentation space. ********************************/ 

HPresSpace = WinBeginPaint /* Returns presentation space handle. */ 

(hwnd, /* Window handle. */ 

0, /* 0 requests a cache presentation space. */ 

0); /* Address of variable to set to invalid region: none.*/ 

/*** Obtain the coordinates of the client window. ****************************/ 

WinQueryWindowRect 

(hwnd, /* Window handle. */ 

SRect); /* Structure to receive coordinates. */ 

/*** Erase the existing contents of the screen. ******************************/ 


WinFillRect 

(HPresSpace, 
&Rect, 
CLR_WHITE); 


/* Draws a filled rectangular area. */ 
/* Presentation space handle. */ 
/* Structure containing window coordinates. */ 
/* Color to use (white). */ 


/*** Print the line of text. ************************************************/ 

WinDrawText /* Draws a single line of formatted text into a rectangle. */ 
(HPresSpace, /* Presentation space handle. */ 

Oxffff, /* Length of string: Oxffff means 0 terminated.*/ 

Message, /* Text to be displayed. */ 

&Rect, /* Coordinates of rectangle containing text. */ 

CLR_BLACK, /* Foreground color. */ 

CLR_WHITE, /* Background color. */ 

/* Drawing specifications: */ 

DT_LEFT | /* Left-justify. */ 

DT_T0P); /* Place at top of window. */ 

/*** Release presentation space / revalidate window. *************************/ 


WinEndPaint (HPresSpace); 


return FALSE; 


/* Tells Presentation Manager that */ 
/* redrawing is complete. */ 


} /* end Paint */ 


• Figure 227: 

The source codefile for the example program (continued) 
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V.1" version of the Presentation Manager text editor pre- 

• ■ sented in this chapter accepts the name of a file from the 

command line, reads the file into an internal buffer, and 
• -JL. then displays the beginning of the file within the win¬ 
dow. Although this version displays only as many lines from the head 
of the file as will fit within the client window, the entire file is loaded 
into data structures in memory that will allow subsequent versions of 
the program to efficiently access, display, and manipulate the file data. 
The memory used to store the file is allocated dynamically, so that the 
program can accommodate files of various lengths without reserving a 
data segment of fixed arbitrary size. Also, if the user enlarges the win¬ 
dow on the screen, the program automatically displays additional lines 
from the file so that the window area is always filled (provided the file 
is sufficiently large). 

In this chapter, you will learn how to use the Presentation Manager 
heap-management functions for dynamically allocating blocks of 
memory; you will learn how to handle Presentation Manager errors; 
and you will learn how to display multiple lines of text within a win¬ 
dow in a manner that is independent of the size of the window and the 
resolution of the display device. The chapter also discusses the design 
of the data structures used to store and manage the file data, describes 
the collection of programming macros provided by OS/2, and presents 
several new Presentation Manager functions and messages. Finally, the 
program describes the techniques for loading and displaying specific 
Presentation Manager fonts. 

Note that the complete source code listing for the current version of 
the example program is given in Figure 3.33, at the end of the chapter. 
Several of the Presentation Manager functions called by this program 
require portions of the OS/2 header files that are not automatically in¬ 
corporated simply by including OS2.H. To force the compiler to include 
the required header information, the program defines two constants 
before including OS2.H. Defining the constant INCL_WIN causes in¬ 
clusion of all header information for the window-management (Win) 
functions, and defining INCL_GPI includes all information for the 
graphics (Gpi) functions. Table 3.1 lists the most general of these con¬ 
stants and the header data they cause the compiler to include. In addi¬ 
tion to the constants listed in this table, there are many other constants 
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that you can define to include smaller portions of the header informa¬ 
tion; for example, the constant INCL_WINHEAP incorporates informa¬ 
tion for only a subset of the window-management functions 
(specifically, the heap-management functions, such as those described 
in this chapter). In Table 3.1, the expression "by default" refers to por¬ 
tions of the header files that are automatically included through the 
#include <OS2 8 H> statement. 


• Table 3.1: Constants for Including Presentation Manager Header Information 


Constant 

Header Information Included 

INCL_PM 

All Presentation Manager header 
information (this constant is 
equivalent to defining all of the 
following constants). 

INCL_WIN 

All header information for 
window-management (Win) functions 
(some of this information is included 
by default). 

INCL_GPI 

All header information for graphics 
( Gpi ) functions (some of this 
information is included by default). 

INCL_DEV 

All header information for device 
support (Dev) functions (some of this 
information is included by default). 

INCL_AVIO 

Header information for advanced Vio 
(Vio) functions (none of this 
information is included by default). 

INCLSPL 

Header information for spooler (Spl) 
functions (none of this information is 
included by default). 

INCL_ERRORS 

All constant definitions for error codes 
returned by Presentation Manager 
functions. 
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* MANAGING THE HEAP 

In the example program, the functions and data structures used to 
read the file and manage the internal data buffer are grouped into a dis¬ 
tinct module; this module is located within the single source code file, 
although it could easily be placed within a separate file. The module 
consists of a public section and a private section. The public section 
comprises the constant definitions, variable definitions, and function 
declarations used by both the function module and the main Presenta¬ 
tion Manager program; it is listed in Figure 3.1. The private section con¬ 
sists of the functions themselves and the data structures and definitions 
used internally by these functions. 

The public section is placed above the function main in the example 
program, and the private section is placed near the end of the file (see 
the complete listing in Figure 3.33). If the private section of the module 
were located in a separate source file, the public section could be placed 
in a header file that is included both by the module and by the main 
program. The reason for encapsulating the file-handling functions 
within a separate module is to simplify the logic of the main application 
and to permit you to modify the implementation details of the buffer- 
management code without disturbing the main program. Note that 
under OS/2, you can also implement modules of supporting functions 


/*** Declarations / 

definitions 

for file- and buffer-management module. ******/ 

#define LINEBUFSIZ 

255 

/* 

Size of buffer for holding lines. 

V 

#define ERROPEN 

1 

/* 

Error: opening file. 

V 

^define ERRTOOBIG 

2 

/* 

Error: file too large. 

V 

#define ERRMAXLINES 

3 

/* 

Error: maximum file lines exceeded. 

V 

#define ERRALLOC 

4 

/* 

Error: heap allocation. 

*/ 

void Buflnit (void) 

; 

/* 

Initializes buffer management module. 

V 

char *ErrorMessage 

(int ErrorNumber); 

/* Returns error message string. 

V 

int ReadFile (char 

*FileName); 

/* 

Reads file into editor buffer. 

V 

SHORT GetLineLength 

(int Line); 

/* 

Gets length of line in buffer. 

V 

PCH GetLineAddr (int Line); 

/* 

Gets address of line in buffer. 

V 

int LastLine = 1; 


/* 

Number of last line in buffer. 

*/ 

HHEAP HHeap = NULL; 


/* 

PM heap handle. 

V 


® Figure 3.1: 

The public declarations of the file/buffer-management module 
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as dynamic-link libraries, which could be shared by several application 
programs (see the discussion of dynamic linking in Chapter 1). 

Before initializing the Presentation Manager and creating the mes¬ 
sage queue, the function main calls two procedures belonging to the 
buffer-management module. First, it calls Buflnit (listed in Figure 3.2) 
to initialize the module; this function obtains and stores the selector and 
offset of the temporary buffer LineBuffer, which will be used by other 
functions in the module for holding and manipulating individual lines 
of the file. Note that this buffer is assigned a size of LINEBUFSIZ, which 
is the maximum line length (including the newline character and the 
terminating null) that can be handled by the program. 


void Buflnit (void) /* Initializes the buffer-management module. */ 

{ 

PCH FarPtr ? 

/*** Obtain selector and offset of temporary line buffer. ********************/ 

FarPtr = (char far *)LineBuffer; 

LineSelector = SELECTOROF (FarPtr); 

LineOffset = OFFSETOF (FarPtr); 

} /* end Buflnit */ 


• Figure 3.2: 

The function Buflnit from the example program 

To extract the selector and offset, the program uses two of the macros 
that are supplied by the OS/2 header files. The macro SELECTOROF 
extracts the selector from a far address, and OFFSETOF extracts the of¬ 
fset. Some of these macros are supplied by the general OS/2 header files 
(such as OS2DEF.H), and some are provided by the header files specific 
to the Presentation Manager (for example, PMWIN.H). Table 3.2 lists a 
collection of the more useful macros, including all of those used by the 
versions of the example program presented in this book. The macros 
specific to the Presentation Manager can be grouped into the following 
categories, according to the functions they serve: 

® Macros for preparing parameters to pass to window procedures. 

These macros, which have the form MPFROM..., are commonly 
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used when sending messages to windows through the WinSend- 
Msg function, to be explained in Chapter 4. 

Macros for extracting values from the message parameters 
received by window procedures, which are named mpl and 
mp2 in the example program. These macros have the form 
...FROMMP; an example is SHORT2FROMMP, which is used by 
the function Size, explained later in the chapter. There are also 
several special-purpose macros for extracting information from 
the parameters for specific messages; an example is CPIARMSG, 
which can be used to isolate specific portions of the parameters 
passed with the WM_CHAR message, explained in Chapter 6. 

Macros for preparing values to be returned by window proce¬ 
dures (which have the return type MRESULT). These macros 
have the form MRFROM.... They are not used by the window 
procedures of the example program, which simply return TRUE 
or FALSE. 

Macros for extracting specific values from the number returned 
from a window procedure. These macros have the form ...FROM- 
MR, and can be used to process the value returned by the func¬ 
tion WinSendMsg (which returns whatever value is returned by 
the window procedure to which the message was sent). 


@ Table 3.2: Useful OS/2 Macros 


General-Purpose Macros 



Macro 

Type 

Purpose 

MAKEP(seI, off ) 

PVOID 

Creates an untyped far pointer from 
selector sel and offset off. 

SELECTOROF (p) 

USHORT 

Extracts the selector from far pointer p. 

OFFSETOF(p) 

USHORT 

Extracts the offset from far pointer p. 

MAKETYPEU, type ) 

* 

Converts variable v to type type. 
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* Table 3.2: Useful OS/2 Macros (continued) 


Macro 

Type 

Purpose 

FIELDOFFSET(fype, field ) 

SHORT 

Calculates the byte offset of field 
field within the structure of type type. 

MAKELONG(/, h) 

LONG 

Combines low-order value l and 
high-order value h to make a 32-bit 
signed quantity 

MAKEULONG(Z, h) 

ULONG 

Combines low-order value l and 
high-order value h to make a 32-bit 
unsigned quantity. 

MAKESHORT(Z, h) 

SHORT 

Combines low-order value l and 
high-order value h to make a 16-bit 
signed quantity. 

MAKEUSHORKZ, h ) 

USHORT 

Combines low-order value l and 
high-order value h to make a 16-bit 
unsigned quantity. 

LOBYTE(zy) 

UCHAR 

Extracts the low-order byte from 16- 
bit quantity w. 

HIBYTE(ro) 

USHORT 

Extracts the high-order byte from 16- 
bit quantity w. 

LOUCHAR(ro) 

UCHAR 

Extracts the low-order byte from 16- 
bit quantity iv; same as LOBYTE. 

HIUCHAR(w) 

USHORT 

Extracts the high-order byte from 16- 
bit quantity zv; same as HIBYTE. 

LOUSHORTXD 

USHORT 

Extracts the low-order word (16-bit 
value) from the 32-bit quantity /. 

HIUSHORT(Z) 

USHORT 

Extracts the high-order word (16-bit 
value) from the 32-bit quantity l. 
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© Table 32: Useful OS/2 Macros (continued) __ 

Macros for Preparing Message Parameters 

Macro Type Purpose 


MPFROMP(p) 

MPARAM 

Makes a message parameter type 
from pointer p. 

MPFROMHWND(fencO 

MPARAM 

Makes a message parameter type 
from window handle hzvnd. 

MPFROMCHAR(cW 

MPARAM 

Makes a message parameter type 
from character ch. 

MPFROMSHORT (s) 

MPARAM 

Makes a message parameter type 
from the quantity s. 

MPFROM2.SHORT (si, s2) 

MPARAM 

Makes a message parameter type 
consisting of the low-order value si 
and the high-order value s2. 

MPFROM.SH2CH(s,ucM,udz2) 

MPARAM 

Makes a message parameter type 
consisting of the low-order value s 
and the high-order value formed 
from uchl (low) and uch2 (high). 

MPFROMLONG(Z) 

MPARAM 

Makes a message parameter type 
from the 32-bit quantity l. 

Macros for Extracting Information from Message Parameters 

Macro 

Type 

Purpose 

PVOIDFROMMP(mp) 

PVOID 

Converts message parameter rap to 
an untyped far pointer. 

HWNDFROMMP(mp) 

HWND 

Converts message parameter rap to a 
window handle type. 

CHARI FROMMP(mp) 

UCHAR 

Extracts the lowest-order byte of 
message parameter rap. 

CHAR2FROMMP(mp) 

UCHAR 

Extracts the second byte (from the 
low-order end) of message 
parameter mp. 

CHAR3FROMMP(mp) 

UCHAR 

Extracts the third byte (from the low- 
order end) of message parameter rap. 
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• Table 3.2: Useful OS/2 Macros (continued) 
f— - ’ ' ; -——— 


—-■ —- -■ -- -—-—--——--—1 

Macros for Extracting Information from Message Parameters (continued) j 

Macro 

Type 

Purpose 

CHAR4FROMMP(mp) 

UCHAR 

Extracts the highest-order byte of 
message parameter mp. 

SHORTlFROMMP(mp) 

USHORT 

Extracts the low-order word (16-bit 
value) from message parameter mp. 

SHORT2FROMMP (mp) 

USHORT 

Extracts the high-order word (16-bit 
value) from message parameter mp. 

LONGFROMMP (mp) 

ULONG 

Converts message parameter mp to 
an unsigned long value. 

CHARMSG (pmsg) 

* 

Used to extract message parameters 
for the WM CHAR message; see ex¬ 
planation in Chapter 6. 

MOUSEMS Gipmsg) 

* 

Used to extract message parameters 
for mouse messages; see explanation 
in Chapter 6. 

COMM ANDMSG (pmsg) 

\ 

* 

Used to extract message parameters 
for the WM_COMMAND, 

WM_HELP, and WM_SYSCOM- 
MAND messages; see example in 
Chapter 7. 

j Macros for Preparing Window Procedure Return Values 

1 

s 

1 Macro 

Type 

Purpose 

MRFROMP(p) 

MRESULT 

Converts pointer p to the type for a 
window procedure return value. 

MRFROMSHORT(s) 

MRESULT 

Converts 16-bit value s to the type 
for a window procedure return 
value. 
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• Table 32: Useful OS/2 Macros (continued) 


Macro 

Type 

Purpose 

MRFROM2.SHORT (s2, s2) 

MRESULT 

Forms a window procedure return 
value from the low-order 16-bit 
value si and the high-order 16-bit 
value s2. 

MRFROMLONG (0 

MRESULT 

Converts 32-bit value l to the type 
for a window procedure return 
value. 

Macros for Extracting Values Returned from Messages 

Macro 

Type 

Purpose 

PVOIDFROMMR(mr) 

PVOID 

Converts message return value mr to 
an untyped pointer. 

SHORT1FROMMR (mr) 

USHORT 

Extracts the low-order word (16-bit 
value) from message return value mr. 

SHORT2FROMMR(mr) 

USHORT 

Extracts the high-order word (16-bit 
value) from message return value mr. 

LONGF'ROMMR(mr) 

ULONG 

Converts a message return value to 
an unsigned long type. 


Although the purpose of many of these macros may seem unclear at 
this point, the following chapters will clarify their use, and you can 
refer back to Table 3.2 as additional macros are introduced in sub¬ 
sequent versions of the example program. 

The second procedure that the function main calls before initializing 
the Presentation Manager is ReadFile (listed in Figure 3.3), which 
creates a heap (explained later), and then reads the file line by line into 
blocks of memory dynamically allocated from this heap. The function 
main passes ReadFile the name of the file, which is obtained from the 
command line through argv [1]. 
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int ReadFile /* Reads file into editor, 

(char *FileName) /* Name of file. 


FILE *PtrFile; /* File stream pointer. */ 
long FileLength; /* Size of file. */ 
USHORT HeapSize; /* Size of allocated heap. */ 
NPCH HeapOffset; /* Offset of blocks within heap. */ 
unsigned char LineLength; /* Length of lines. */ 
PCH FarPtr; /* Temporary far pointer. */ 


/*** Open the file. **********************************************************^ 

if ((PtrFile = fopen (FileName,"r")) == NULL) 
return (ERROPEN); 

/*** Obtain and test file length. ********************************************/ 

if ((FileLength = filelength (fileno (PtrFile))) == -1) 
return (ERROPEN); 

if (FileLength > 50000) 
return (ERRTOOBIG); 

/*** Allocate a heap to hold file lines. *************************************/ 


/* Make heap 20% larger than size of file. */ 

HeapSize = (USHORT)(FileLength + FileLength / 5); 

HHeap = WinCreateHeap 

(0, /* Segment address: 0 means allocate new segment. */ 

HeapSize, /* Initial heap size. */ 

0, /* Minimum increase size: 0 means use default. */ 

0, /* Minimum # of dedicated free lists: none. */ 

0, /* Maximum # of dedicated free lists: none. */ 

0); /* Options: none. */ 


/*** obtain selector to heap segment. ****************************************/ 

FarPtr = WinLockHeap (HHeap); 

Heapselector = SELECTOROF (FarPtr); 

/*** Read each line in file into a separate block allocated from heap. *******/ 
LastLine = -1; 

while (fgets (LineBuffer,LINEBUFSIZ-1,PtrFile) 1= NULL) 

{ 

/*** Test for line limit — update 'LastLine'. *********************/ 
if (++LastLine >= MAXLINES) 
return (ERRMAXLINES); 

/*** calculate length of line. *************************************/ 
LineLength = (unsigned char)strlen (LineBuffer) + 1;/* Include null*/ 

/*** insert '\n' into overlength lines. ****************************/ 
if (LineLength == LINEBUFSIZ - 1 && 


® Figure 33: 

The function ReadFile from the example program 
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LineBuffer [LINEBUFSIZ - 3] != '\n') 

{ 

LineBuffer [LINEBUFSIZ - 2] = '\n'; 

LineBuffer [LINEBUFSIZ - 1] = '\0'; 

++LineLength; 

} 

/*** Allocate a block from heap to hold the line. ******************/ 
HeapOffset = WinAllocMem 

(HHeap, /* Heap handle. */ 

LineLength); /* Length of line to store. */ 

if (HeapOffset == NULL) 
return (ERRALLOC); 

/*** copy line into heap block. ************************************/ 
movedata (LineSelector,LineOffset,HeapSelector, 

(unsigned)HeapOffset,LineLength); 

/*** insert line information into the table. ***********************/ 
LineTable [LastLine].LineAddress = MAKEP (HeapSelector,HeapOffset); 
LineTable [LastLine].LineLength = LineLength; 

) 

/*** Close the file. *********************************************************/ 
fclose (PtrFile); 
return (0) ; 

} /* end of ReadFile */ 


® Figure 3.3: 

The function ReadFile from the example program (continued) 

ReadFile first opens the file by calling fopen. Note that ReadFile 
employs the high-level file-management functions fopen, fgets, and 
fclose, which are provided by the standard C library. Although these 
functions may not be the most efficient means for reading the file and 
extracting individual lines, they are convenient to use, are familiar to C 
programmers, and permit the example code to focus on the unique fea¬ 
tures of Presentation Manager programming. The section on Enhance¬ 
ments, near the end of the chapter, offers some suggestions for 
improving the file-handling efficiency. 

Once the file is opened, ReadFile tests the length of the file by calling 
the C function filelength. If the file is larger than 50,000 bytes, ReadFile 
returns an error message. Therefore, 50,000 bytes is the maximum file 
size that can be handled by the current version of the text editor, for 
reasons that will be explained shortly Suggestions for greatly increas¬ 
ing this limit are discussed in the Enhancements section. 
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ReadFile next calls the Presentation Manager function WinCreate- 
Heap (Figure 3.4) to create a heap for storing and managing the file data. 
In general, a heap is a block of memory out of which the system can 
dynamically allocate smaller blocks of memory WinCreafeHeap 
creates and initializes a heap that is managed by the Presentation 
Manager; you can allocate and free blocks of memory from this heap 
using the functions that will be described in this section. 

As you can see from Figure 3.4, a Presentation Manager heap can be 
placed in one of two locations. First, you can create a heap within the 


WinCreafeHeap 

Purpose: 

Creates and initializes a heap for dynamically allocating 
blocks of memory. 

Prototype: 

HHEAP APIENTRY WinCreateHeap 
(ushort selHeapBase, Selector of the segment to contain the 
heap (the application program must 
have already explicitly allocated a 
segment for the heap). A value of 0 
means either to locate the heap at the 
end of the application's automatic data 
segment (if the next parameter, 
cbHeap, is also 0), or to allocate a new 
segment for a heap (if the next 
parameter is not 0). 

ushort cbHeap, Initial size of heap in bytes (note that 

the system will automatically expand 
the heap to fill memory requests up to 
the 64-kilobyte segment limit). A value 
of 0 means either that the heap is being 
placed in the program's automatic 
data segment (if the first parameter, 
selHeapBase, is 0), or that the program 
has already explicitly allocated a new 
segment for the heap (if the first 
parameter contains a selector). 


• Figure 3.4: 

The WinCreateHeap Presentation Manager function 




The following is a summary of the 
effects of various combinations of the 
first two parameters. 

segHeapBase cbHeap Effect 

0 0 Places heap at 

end of program's 
automatic data 
segment 

0 !=0 Allocates a new 

separate segment 
for the heap from 
the operating 
system 

!=0 0 Program has allo¬ 

cated a separate 
segment by call¬ 
ing DosAllocSeg; 
places heap 
within this seg¬ 
ment 

!=0 !=0 Applies only to 

dynamic-link 
library modules 

Minimum number of bytes by which 
the heap must be expanded if it 
requires additional memory to fulfill 
a memory allocation request. A value 
of 0 means to use the default amount 
(512 bytes). 

Minimum block size to be given a 
dedicated free list. 

Maximum block size to be given a 
dedicated free list. 

• Figure 3.4: 

The WinCreateHeap Presentation Manager function (continued) 


USHORT cbGrow, 

USHORT cbMinDed, 
USHORT cbMaxDed, 
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ushort f Options) ; Options; the only option currently 

supported is HM_MOVEABLE, which 
specifies that the heap should support 
movable objects. A value of 0 indicates 
no options. 

Return Value: 

A heap handle if the heap was successfully created, and 0 
otherwise. 

Notes: 

The cbMinDed and cbMaxDed parameters allow you to 
specify a range of block sizes that will be placed on dedi¬ 
cated free lists. A dedicated free list is a list of free blocks of a 
given size; such a list allows these blocks to be allocated with 
maximum efficiency. 

Related Functions: 

WinDestroyHeap (Figure 3.5) 

WinAllocMem (Figure 3.7) 

WinFreeMem (Figure 3.10) 


• Figure 3.4: 

The WinCreateHeap Presentation Manager function (continued) 

program's automatic data segment. The automatic (or default) data seg¬ 
ment contains the program's initialized, uninitialized, and constant 
data, as well as the program stack. (A large data model C program may 
have one or more additional segments to contain data that does not fit 
within the automatic segment. The size of the stack is determined by the 
STACKSIZE statement in the linker definition, .DEF, file.) You can also 
reserve a given number of bytes for a local heap at the end of the auto¬ 
matic data segment through the HEAPSIZE statement in the linker 
definition file; the example program reserves 1024 bytes for a local 
heap. By assigning 0 to the first two parameters passed to WinCreate¬ 
Heap (selHeapBase, the heap selector, and cbHeap, the heap size), you 
cause the Presentation Manager to initialize a heap within the area at 
the end of the automatic data segment that was reserved for this 
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purpose; the size of this heap is the size given by the HEAPSIZE state¬ 
ment. The advantage of locating the Presentation Manager heap within 
the automatic data segment is that you can efficiently address this 
memory using near pointers (that is, pointers containing only the offset 
portion of the address; the selector for the automatic data segment is al¬ 
ready contained in the DS register, and therefore pointers do not have to 
include the selector value). 

Alternatively, you can locate the heap within an entirely separate 
segment that is not reserved when the program is loaded, but rather is 
allocated after the program begins running. By assigning 0 to the first 
parameter (selHeapBase, the heap selector) and by assigning the 
desired initial heap size to the second parameter (cbHeap), the example 
program causes WinCreateHeap to allocate a new segment from the 
operating system and initialize this segment as a heap. The initial size 
requested for this heap is based upon the length of the file. The ad¬ 
vantage of placing the heap within a newly allocated data segment is 
that the program need allocate only the amount of memory actually re¬ 
quired for storing the file; if the heap were located within the automatic 
data segment, you would have to reserve an arbitrary large amount of 
memory through the HEAPSIZE definition file command in order to ac¬ 
commodate various file sizes. Also, a separate segment can contain a 
larger heap than the automatic data segment, which must also hold the 
program's stack and data. 

Note that the value passed as the second parameter to WinCreate¬ 
Heap (cbHeap) specifies the initial heap size; the Presentation Manager 
will automatically enlarge the heap (up to the 64-kilobyte segment size 
limit) if it cannot fill a given allocation request. The example program 
requests an initial heap size that is 20 percent larger than the length of 
the file so that the Presentation Manager need not immediately expand 
the heap; this added memory will accommodate any additional infor¬ 
mation the system must store to maintain the heap, and it will allow the 
user to add data to the file. If the file size continues to grow, the Presen¬ 
tation Manager will eventually have to call the OS/2 kernel to expand 
the segment containing the heap. 

Since the heap is stored within a single segment, however, it cannot 
grow beyond the segment size limit of 64 kilobytes (an unfortunate con¬ 
sequence of the segmented architecture of the 80286 processor). Conse¬ 
quently, the program will not process a file that is longer than 50,000 
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bytes (allowing for file expansion). Also, if the file size grows to the 
maximum size (in later versions of the program that allow data entry), 
the program will save the current contents of the file and will quit with 
an error message. As mentioned in the section on Enhancements, you 
can use multiple heaps to overcome this size limitation and take ad¬ 
vantage of the large memory space afforded OS/2 applications. 

The next parameter to WinCreateHeap, cbGrow, specifies the mini¬ 
mum number of bytes by which the system will expand the heap when 
additional memory is required. The function ReadFile sets this 
parameter to 0 to request the default amount (512 bytes). The next two 
parameters, cbMinDed and cbMaxDed, specify a range of specific 
block sizes that are to be managed with dedicated free lists. The system 
can place a collection of free blocks that have the same size within a 
dedicated list to increase the efficiency of allocating these blocks. If all of 
the blocks used by a program are the same size (or if there is a narrow 
range of sizes), it should request the system to use a dedicated free list 
(or lists, if there is a range of sizes) for these blocks. As you will see, 
however, the example program allocates separate blocks from the heap 
for each line of the file; since these blocks are of random lengths, the 
program assigns 0 to cbMinDed and cbMaxDed, indicating that no 
dedicated lists are desired. Note that WinCreateHeap returns a handle 
to the heap (stored in HHeap), which must be passed to all subsequent 
heap functions. 

Before the application terminates (in the Quit function, described in 
the next section) it calls WinDestroyHeap (Figure 3.5) to free the 
memory segment containing the heap. 

Although WinCreateHeap returns a handle, you may have noticed 
that an important value is still missing: the selector of the memory seg¬ 
ment that contains the heap (remember that since the heap is not in the 
automatic data segment, the program needs the selector to construct the 
far pointer used to address locations within the heap). The far address 
of a heap is returned by the Presentation Manager function WinLock- 
Heap (Figure 3.6); the program calls this function and then extracts the 
selector value and stores it in the variable HeapSelector. 

The function ReadFile now enters the main while loop that reads 
lines from the file and inserts them into the heap. With each repetition of 
the loop, the program performs the following steps: 
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• It reads the next line from the file into the temporary buffer Line- 
Buffer, by calling the C library function fgets. 

• It updates the variable LastLine, which contains the number of 
the last line stored in the heap (and quits if the maximum num¬ 
ber of lines, MAXLINES, is exceeded). 

• It calculates the length of the line (by calling strlen) and allocates 
a block of memory from the heap just large enough to contain 
the line, including the newline character and the terminating 
null. The block is allocated by calling the Presentation Manager 
function WinAllocMem (Figure 3.7). Note that if the line is over¬ 
sized (that is, it exceeded the maximum buffer length passed to 
fgets and therefore does not contain a newline character), the 
program inserts a newline. 


WinDestroyHeap 

Purpose: 

Destroys a heap previously created by WinCreateHeap. 
Prototype: 

HHEAP APIENTRY WinDestroyHeap 
(hheap hHeap) ; Heap handle, returned by a prior call to 
WinCreateHeap. 

Return Value: 

0 if the function is successful, and a nonzero value if an error 
occurred. 

Related Functions: 

WinCreateHeap (Figure 3.4) 


• Figure 3.5: 

The WinDestroyHeap Presentation Manager function 
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• It copies the line from the temporary buffer into the newly allo¬ 
cated block in the heap, using the C library function movedata, 
which supports intersegment data moves. Unfortunately, it is not 
possible to read the data directly into the heap block, since the 
length of the line must be calculated before this block is allocated. 

• It places the far address of the line (constructed using the OS/2 
macro MAKEP) and the length of the line into the next available 
entry in the line table, LineTable. 


WinLockHeap 

Purpose: 

Supplies the far address of the base of the segment contain¬ 
ing the specified heap. 

Prototype: 

PVOID APIENTRY WinLockHeap 

(hheap hHeap) ; The heap handle returned by a prior call to 
WinCreateHeap. 

Return Value: 

A far pointer to the base of the memory segment containing 
the heap. 

Notes: 

You must call this function to obtain the selector required to 
access a heap that is not located within the program's auto¬ 
matic data segment. 

Related Functions: 

WinCreateHeap (Figure 3.4) 

• Figure 3.6: 

The WinLockHeap Presentation Manager function 
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• After the last line is safely stored in the heap, the loop exits and 
the program closes the file by calling the C library function 
fclose. 


WinAllocMem 

Purpose: 

Allocates a block of memory from a Presentation Manager heap. 
Prototype: 

NPBYTE APIENTRY WinAllocMem 

(hheap hHeap, Handle to the heap returned by 

WinCreateHeap. 

ushort cb) ; Size of the requested block in bytes. 

Return Value: 

The offset address of the allocated block, or NULL if the 
function fails. 

Notes: 

If the heap is currently not large enough to supply the re¬ 
quested block, WinAllocMem attempts to enlarge the seg¬ 
ment containing the heap. If, however, it is unable to expand 
the heap, it returns NULL. Note that this function returns a 
near address (offset only); to address a heap located outside 
of the program's automatic data segment, you must use a far 
pointer containing the heap segment selector (which can be 
obtained from WinLockHeap). 

Related Functions: 

WinCreateHeap (Figure 3.4) 

WinLockHeap (Figure 3.6) 

WinFreeMem (Figure 3.10) 


« Figure 3.7: 

The WinAllocMem Presentation Manager function 
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It may seem costly to store each line within a separate allocated 
block; as you will see, however, this method greatly facilitates display¬ 
ing, modifying, inserting, and deleting individual lines. Also, since all 
of the blocks are located within a single segment, the Presentation 
Manager can allocate and free them quickly. (Allocating and freeing 
separate segments requires calling the operating-system kernel, and is a 
relatively slow process. The Presentation Manager needs to call the 
operating system only if it must enlarge the size of the heap.) 

The address and length of each line is stored in an entry in the array 
LineTable, which is defined as follows: 

#define MAXLINES 4096 /* Maximum number of lines */ 

/* in buffer */ 


static struct 
{ 

PCH LineAddress; /* Far address of line */ 

/* in heap. */ 

unsigned char LineLength; /* Length of line, */ 

/* including \n, \0. */ 

} 

LineTable [MAXLINES]; 

Storing the addresses in this table provides the program rapid ran¬ 
dom access to any line in the file. Storing the line lengths eliminates the 
need for the window procedure to calculate the length of a each line 
that it displays (as you will see, the function used to print a line in the 
window requires the line length as a parameter). 

The main application obtains the address of a given line by passing 
the line number to the function GetLineAddr, and obtains the length of 
a line by passing the line number to GetLineLength. Both of these func¬ 
tions simply check that the line number is within the valid range and 
then return the desired value from the appropriate entry in LineTable. 
Note that the main application does not have direct access to Line- 
Table this encapsulation of data makes it simple to modify the data 
structure used to manage the file without affecting the main program. 
GetLineAddr and GetLineLength are both contained within the buffer- 
management module and are listed in Figure 3.8. 
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Note that the number of lines that the program can accommodate is 
limited by the number of elements in LineTable, which is currently set 
to 4096 (MAXLINES); this is a generous number of lines, considering 
that the file size is presently limited to less than 64 kilobytes. The overall 
data structure used to access and manipulate the lines of the file is il¬ 
lustrated in Figure 3.9. 

Memory blocks allocated from the heap may be freed by calling Win- 
FreeMem. This function is described in Figure 3.10, although it is not 
used until the version of the example program presented in Chapter 6. 


• HANDLING ERRORS 

The basic OS/2 services (Dos, Kbd, Vio, and Mou functions) use a 
simple and consistent scheme for reporting errors: if the function is suc¬ 
cessful, it returns 0; otherwise, it returns a nonzero error code. The 
return values of these functions are therefore reserved for communicat¬ 
ing the error status. (Other values are returned by assigning them to 
variables, the addresses of which are passed as parameters.) Many of 


SHORT GetLineLength (int Line) /* Gets length of line in buffer. */ 

{ 

if (Line < 0 || Line > LastLine) 
return 0; 

else 

/* Extract line length from table, excluding '\n' and '\0'. */ 

return LineTable [Line].LineLength - 2; 

) /* end GetLineLength */ 


PCH GetLineAddr (int Line) /* Gets address of buffer line. */ 

{ 

if (Line < 0 || Line > LastLine) 
return NULL; 

else 

return LineTable [Line].LineAddress; 

} /* end GetLineAddr */ 




Figure 3,8 : 

The functions GetLineLength and GetLineAddr from the example program 
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the Presentation Manager functions, however, directly return informa¬ 
tion other than the error status (for example, functions that return hand¬ 
les). These functions must therefore indicate an error condition by 
returning a special value that is outside the normal range of return 
values. Accordingly, the value returned when an error occurs depends 
upon the specific Presentation Manager function, and is given in the 
documentation for each function. Table 3.3 lists the special error return 
values for the Presentation Manager functions used by the program 
given in this chapter. 

You can see from Table 3.3 that the special error return value is often, 
but not always, equal to 0 (or 0L). Also, unlike the basic OS/2 services, 
the Presentation Manager functions do not directly supply a code in¬ 
dicating the specific error that occurred. You can obtain this information 
by calling WinGetLastError (Figure 3.11), which returns a 32-bit error 


Line Number 


LastLine 


• Figure 3.9: 

The data structure used to manage the file lines 















Managing Memory 103 


© 


code; the high-order word contains a code for the severity level, and the 
low-order word contains a code indicating the specific error. You can in¬ 
clude identifiers in your program for both of these types of errors by 
defining the constant INCL_ERRORS before including OS2.H. See the 
latest version of the appropriate header file (PMWIN.H for the Win 
functions and PMGPI.H for the Gpi functions) for a list of the error iden¬ 
tifiers and the corresponding codes that can be returned by the Presen¬ 
tation Manager functions (the error code constants begin with the 
prefix PMERR). 


WinFreeMem 

Purpose: 

Frees a memory block from a heap managed by the Presen¬ 
tation Manager. 

Prototype: 

NPBYTE APIENTRY WinFreeMem 
(hheap hHeap , Handle to the heap returned by 

WinCreateHeap. 

npbyte npMem , Offset of the memory block to be 

freed, returned by a prior call to 
WinAllocMem (or WinReallocMem). 
ushort cbMem) ; The size of the block to be freed. 

Return Value: 

NULL if the function is successful; otherwise, it returns the 
value passed in the npMem parameter. 

Related Functions: 

WinCreateHeap (Figure 3.4) 

WinAllocMem (Figure 3.7) 

® Figure 3.10: 

The WinFreeMem Presentation Manager function 
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Table 33: Special Error Return Values for the Presentation Manager Functions Used in This Chapter 


Function 

Special Value Returned on Error 

GpiCharStringAt 

GPLERROR (OL) 

GpiCreateLogFont 

FALSE (0) 

GpiLoadFonts 

FALSE(O) 

GpiQueryFonts 

No special value 

GpiSetCharSet 

FALSE(O) 

GpiSetColor 

FALSE (0) 

WinAllocMem 

NULL (0) 

WinBeginPaint 

NULL (OL) 

WinCreateHeap 

NULL (OL) 

WinCreateMsgQueue 

NULL (OL) 

WinCreateStdWindow 

NULL (OL) 

WinDefWindowProc 

Depends upon the message 

WinDestroyHeap 

Nonzero value 

WinDestroyMsgQueue 

FALSE (0) 

WinDestroyWindow 

FALSE (0) 

WinDispatchMsg 

Depends upon the message 

WinEndPaint 

FALSE (0) 

WinFillRect 

FALSE (0) 

WinFreeMem 

Nonzero value (= npMem parameter) 

WinGetMsg 

No special value 

WinGetPS 

NULL (0L) 

Winlnitialize 

NULL (0L) 

WinLockHeap 

NULL (0L) 

WinMessageBox 

DID JERROR (OxFFFF) 

WinQueryWindowRect 

FALSE (0) 

WinRegisterClass 

FALSE (0) 

WinReleasePS 

FALSE (0) 

WinTerminate 

FALSE (0) 




WinGetLastError 


Purpose: 

Returns the system error code set by the last Presentation 
Manager function that failed, and resets the system error 
code to 0. 

Prototype: 

ERRORID APIENTRY WinGetLastError 
(hab hab); Anchor block handle. 

Return Value: 

A 32-bit error code, containing the following values: 

High-order word One of the following codes for the j 
general severity level: 

SEVERITYNOERROR 
SEVERITY_WARMING 
SEVERITYERROR 
SEVERITY_SEVERE 
SEVERITY JJNRECOVERABLE 

Low-order word A code indicating the specific error. 

These codes are listed in Appendix D 
for all Win functions; for other 
Presentation Manager functions, 
refer to the function description in 
the technical documentation. 

Related Functions: 

WinGetErrorlnfo 
WinFreeErrorlnfo 

• Figure 3.11: 

The WinGetLastError Presentation Manager function 
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In summary, you can handle an error condition that occurs when calling 
a Presentation Manager function through the following series of steps: 

1. Include the constant definitions for error codes by defining 
INCL_ERRORS before including OS2.H. 

2. Before calling the Presentation Manager function, call WinGet- 
LastError to reset the system error status for the current program 
thread to 0. 

3. Call the Presentation Manager function, and test the return value. 

4. If the return value equals the special error value for that func¬ 
tion, then call WInGetLastError to obtain a code for the specific 
error. 

5c Branch to an appropriate error-handling routine, depending 
upon the error code returned by WInGetLastError. 

For example, the following code fragment handles the error condi¬ 
tions that may occur when calling WimAllocMem. 

#define INCL_WIN 
#define INCL_ERRORS 
#include <OS2.H> 

ERRORXD Error; 

NPCH HeapOffset; 


HeapOffset = WinAllocMem (HHeap, LineLength); 
if (HeapOffset == NULL) 

{ 

Error = WinGetLastError (HAncBlk); 
switch (LOUSHORT (Error)) 

{ 

case PMERR__HEAP _OUT_OF_MEMORY : 

/* Manage heap out of memory error. */ 

case PMERR_HEM>_MAX__SIZE_REACHED: 

/* Manage heap reached maximum size error. */ 
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default: 

/* Manage any other heap-allocation error. */ 

} 

} 

Note that you can also call the Presentation Manager functions Win- 
GetErrorlnfo and WinFreeErrorlnfo to obtain more detailed error in¬ 
formation. See the Presentation Manager technical documentation for 
information on these two functions. 

To simplify the code, the example programs presented in this book 
perform only minimal error checking. Correct programming should 
eliminate most errors; some errors, however, cannot easily be 
prevented. For example, if the user enters more data into the file than 
can be held within the single segment used to contain the heap, the 
function WinAllocMem returns the special value NULL to indicate that 
the maximum heap size has been reached. In this case, the function 
ReadFile simply returns the value ERRALLOC indicating a general 
memory-allocation failure, without calling WinLastError to determine 
the specific error (if WinLastError were called, it would return the value 
PMERR_HEAP_MAX_SIZE_REACHED). Note that ERRORALLOC is 
one of a set of error codes that can be returned by the buffer-manage¬ 
ment module; these codes are defined at the top of the example pro¬ 
gram and are listed in Figure 3.1. The buffer-management module also 
provides a function, ErrorMessage (listed in Figure 3.12), that returns 
the string corresponding to a given error code. 

When the main part of the example program encounters a fatal error, 
it calls the utility function ErrorQuit (listed in Figure 3.13), passing it an 
error message. ErrorQuit formats the message and then calls Win- 
MessageBox (Figure 3.14) to display the message. It then terminates the 
program by calling the function Quit (also listed in Figure 3.13). Note 
that both the functions main and ErrorQuit terminate the program by 
calling Quit, which releases the heap and performs the other final tasks 
required of a Presentation Manager program that were explained in 
Chapter 2. 

The function WinMessageBox displays a message box, which is a 
temporary window containing a specified title and message, and one of 
four standard icons. The message box also contains one or more push 
buttons (explained in Chapter 8) that you specify when you call this 
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function. When the user selects a push button, WinMessageBox 
removes the temporary window and returns control to the calling pro¬ 
gram. The message box created by ErrorQuit displays the name of the 
program as the title (the fourth parameter, pszCaption) and prints 
the error message as the text inside the box (the third parameter, psz~ 
Text). The box also contains an icon in the shape of a hand (recom¬ 
mended for serious errors, and specified through the sixth parameter, 
flStyle) and a single push button labeled Ok (also specified through the 
flStyle parameter). When the user presses the Spacebar or Enter key, or 
clicks the mouse with the pointer inside the push button, the message 
box is removed and control returns to ErrorQuit. This message box is 
illustrated in Figure 3.15. 

Note that the first parameter passed to WinMessageBox (hwnd- 
Parent) is the handle of the owner of the message box window; the ex¬ 
ample program specifies the desktop window (HWND_DESKTOP). 
Accordingly, the message box is a top-level window and is not confined 
to the area of the frame window, but can be placed anywhere on the 
screen. (You do not control the initial placement or size of this window; 
the system automatically centers it in the screen and makes it large 
enough to accommodate the message text.) 


char *ErrorMessage /* Returns a string that describes an error code. */ 

(int ErrorNumber) /* The error code. */ 

{ 

static char *MessageTable [] = 

{ 

"no error", 

"file open failure", 

"file too large", 

"maximum lines exceeded", 

"heap memory allocation failed", 

"unidentified error" 

} ; 

if (ErrorNumber >= sizeof (MessageTable) / sizeof (char *)) 

ErrorNumber = sizeof (MessageTable) / sizeof (char *) - 1; 

return MessageTable [ErrorNumber]; 

} /* end ErrorMessage */ 


• Figure 3.12: 

The function ErrorMessag efrom the example program 
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The second parameter, hwndOwner, gives the owner of the message 
window. The owner of a window is distinct from the parent of the win¬ 
dow (which was explained in Chapter 2). Unlike the parent-child 
relationship, a window is not confined to the area occupied by its 
owner, and it is not automatically destroyed when its owner is de¬ 
stroyed. The owner-owned relationship is optional; a window does not 
need to have an owner, and you can change the owner of a window 
through the function WinSetOwner. In general, a control window (such 
as a scroll bar, discussed in Chapter 4) sends a message to its owner 
when it receives input from the user. The owner specified through the 


void ErrorQuit /* Terminate program due to fatal error condition. */ 

(char ^Message) /* Error message to display to user. */ 

{ 

char Buffer [60]; 


sprintf (Buffer,"Program Error: %s",Message); 


WinMessageBox 

/* 

Display a message 

box. 

V 

(HWND_DESKTOP, 

/* 

Handle of parent: 

desktop window. 

*/ 

HFrame, 

/* 

Handle of owner: 

frame window. 

V 

Buffer, 

/* 

Message text. 


*/ 

"PM Text Editor", 

/* 

Caption. 


*/ 

0, 

/* 

Help window ID: 

not needed. 

*/ 

MB OK | 

/* 

Display an 'OK' button. 

V 

MB_ICONHAND); 

/* 

Display a hand icon. 

*/ 

Quit (1); 

/* 

Call normal termination function. 

V 


} /* end ErrorQuit */ 


void Quit 

(int ErrorCode) /* Process termination status. */ 

/* 

Calls Presentation Manager termination functions and ends program 
with specified error code. 

*/ 

{ 

if (HHeap 1= NULL) 

WinDestroyHeap (HHeap); 

WinDestroyWindow (HFrame); 

WinDestroyMsgQueue (HMesQue); 

WinTerminate (HAncBlk); 
exit (ErrorCode); 

} /* end Quit */ 


• Figure 3.13: 

The functions ErrorQuit and Quit from the example program 
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WinMessageBox 

Purpose: 

Displays a message box window. 


Prototype: 


USHORT APIENTRY WinMessageBox 


(HWND hwndParent, 


HWND hwndOwner, 


PSZ pszText, 


PSZ pszCaption, 


USHORT idWindow, 


USHORT flStyle); 


The parent of the message box 
window (HWND_DESKTOP if the 
message box is to be a top-level 
window). 

The owner of the message box 
window; this window is activated 
when WinMessageBox returns. 
Address of the null-terminated string 
to be displayed within the message 
box; you can insert carriage-return 
characters within this string to display 
multiple lines. 

Address of a null-terminated string to 
be displayed as the title of the message 
box; if this parameter is NULL, the 
default title Error is displayed. 

The window ID of the message box 
window; if no ID is required, you can 
set this parameter to 0. 

The message box style; you can specify 
one or more of the following style 
values (they should be combined 
using the I operator): 

Effect 

)K Include push 

button labeled 
Ok 

MB OKCANCEL Include Ok and 

Cancel push but¬ 
tons 


Style 
MB OK 


MB RETRYCANCEL 


Include Retry 
and Cancel push 
buttons 


• Figure 3.14: 

The WinMessageBox Presentation Manager function 
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MB ABORTRETRY- 

Include Abort , 

IGNORE 

Retry , and Ignore 
pu sh buttons 

MBYESNO 

Include Yes and 

No push buttons 

MBYESNOCANCEL 

Include Yes, No , 
and Cancel push 
buttons 

MB_HELP 

Include a Help 
push button 

MB_ICONHAND 

Include a hand 
icon; recom¬ 
mended for 
serious errors 

MB_ICON QUESTION 

Include a ques¬ 
tion mark icon; 
recommended 
to warn and 
elicit response 
from user 

MB ICON- 

Include an ex¬ 

EXCLAMATION 

clamation mark 
icon; recom¬ 
mended for 
warnings 

MBJCONASTERISK 

Include an 
asterisk icon; 
recommended 
for reporting 
status information 

MB JDEFBUTTON 1 

First button is 
default (that is, 
selected through 
the Enter key) 

MBDEFBUTTON2 

Second button is 
default 

MB DEFBUTTON3 

Third button is 
default 


• Figure 3.14: 

The WinMessageBox Presentation Manager function (continued) 
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MB 

MB 

_APPLMODAL 

_SYSTEMMODAL 

The message box 
is application 
modal (user can¬ 
not switch 
to another win¬ 
dow in current 
application) 

The message box 
is system modal 
(user cannot 
switch to other 
applications) 

Return Value: 



One of the following values, indicating which button the 
user selected or an error status: 

Return Value 

Meaning 


DID_ERROR 

An error occurred 

MBID_ABORT 

Abort button was selected 

MBID_CANCEL 

Cancel button was selected, or Esc 
was pressed 

MBIDJGNORE 

Ignore button was selected 

MBID_NO 

No button was selected 

MBIDOK 

Ok button was 

selected 

MBID_RETRY 

Retry button was selected 

MBID_YES 

Yes button was 

selected 


• Figure 3.14: 

The WinMessageBox Presentation Manager function (continued) 


hwndOwner parameter is the window that becomes active when Win¬ 
MessageBox returns (the notion of an active window is also discussed 
in Chapter 4). The example program specifies the frame window 
(HFrame) as the owner of the message box. 

Note also that since the frame window is specified as the owner of 
the message box window, you cannot call WinMessageBox until after 
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• Figure 3.15: 

The message box displayed by the example program 


the frame window has been created though the call to WinCreateStdb 
Window. The example program, however, must call ReadFile before 
creating the window (remember that creating the window causes the 
WMJPAINT message to be sent to the window procedure, which dis¬ 
plays file data from the buffer). Accordingly, the function main retains 
the error code returned from ReadFile, and then tests this code—pos¬ 
sibly calling ErrorQuit—after the call to WinCreateStdWindow. 


• DISPLAYING TEXT 

The version of the example program presented in Chapter 2 simp¬ 
ly displayed a string that was justified at the upper left corner of the 
client window. This version illustrated the concept of centralizing all 
code for drawing window data within a single routine, which is in¬ 
voked whenever an event external to the program requires that data be 
redrawn, or whenever the program itself needs to modify the display. 

The version of the example program presented in the present chapter 
prints as many lines from the beginning of the file as will fit within the 
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client window. This program illustrates two more concepts important 
for displaying data within a Presentation Manager window: 

• Keeping the appearance of the display independent of the resolu¬ 
tion of the display device 

• Adjusting the display for the current size of the window 

To achieve these two objectives, the window procedure belonging to 
the current version of the example program needs to process three mes¬ 
sages: WM_CREATE, WM_SIZE, and WM_PAINT (the previous ver¬ 
sion processed only the WM_PAINT message). As in the previous 
version, all other messages are passed to the function WinDefWindow- 
Proc for default processing. 


The WM_CREATE Message 

The WM_CREATE message (Figure 3.16) is sent to the window proce¬ 
dure immediately after the window is created but before it becomes visible; 
this message allows the window procedure to perform required initialization 
tasks. In the example program, the WM CREATE message is processed by 
the function Create (listed in Figure 3.17), which loads the required charac¬ 
ter font and stores the dimensions and other attributes of this font. As you 
will see in the explanation of the WMJPAINT message, the font loaded by 
Create is used to display the file data within the window. 

The function Create first calls GpiLoadFonts (Figure 3.18) to load the 
set of Courier fonts from the font file COURIER.FON. (Note that you 
must specify the full path name for this file.) 

The Courier font style is selected because it is the only standard font 
style supplied with the Presentation Manager that consists of fixed- 
width characters. Since all characters have the same width, they are 
aligned in vertical columns, which is the appropriate style for writing 
programs and other text files. (Also, using fixed-width characters great¬ 
ly simplifies the logic for positioning the cursor and manipulating the 
data on the screen.) The other loadable fonts, as well as the default sys¬ 
tem font, contain proportionally spaced characters. With these fonts, char¬ 
acters do not occupy the same width; rather, narrow characters such as 
1 are contained in a smaller horizontal space than wide characters such 
as W. Note that the example program in Chapter 2 (Figure 2.27) simply 
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used the default system font; also, the system displays titles, menu 
labels, and other textual data using the default font. Therefore, these 
items all appear with proportionally spaced characters. 

The function Create next calls WinGetPS (Figure 3.19) to obtain a 
handle to a presentation space. WinGetPS supplies a cache presenta¬ 
tion space, which was explained in Chapter 2. This function is called be¬ 
cause the next function invoked (GpiQueryFonts) requires a 
presentation space handle. 

Once the program has obtained a presentation space, it calls Gpi- 
QueryFonts (Figure 3.20) to obtain detailed information on a selected 
font. Note that a given font file typically contains several distinct fonts; 
once the font file is loaded, all of the fonts it contains are available to the 


WM_CREATE 

Purpose: 

Sent by the system to a window when it is first created. It 
allows the window procedure to perform initializations. 

Parameters: 

mparam mpl Address of control data that was passed to 

the function WinCreateWindow. 
mparam mp2 Address of a CREATESTRUCT structure 

containing information on the window that 
is being created. 

Return Value: 

Return FALSE to continue window creation. 

Notes: 

This message is sent after the window is created but before it 
becomes visible. 


• Figure 3.16: 

The WM_CREATE Presentation Manager message 
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program. These fonts generally conform to a common basic style (such 
as the Courier style in COURIER.FON), but differ in the size of the let¬ 
ters; the file may also include fonts that provide variations on the basic 
style, such as boldface or italic letters. 


MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

HPS HPresSpace; /* Presentation space handle., */ 

FONTMETRICS Metrics; /* Structure to hold font dimensions. */ 

LONG NumberStructs =1; /* Number of structures from GpiQueryFonts. */ 

/*** Load Courier mono-space font. *******************************************/ 
GpiLoadFonts 

(HAncBlk, /* Anchor block handle. */ 

"\\0S2\\DLL\\C0URIER.FON"); /* Full path name of font file. */ 


/*** Obtain a handle to a presentation space. ********************************/ 
HPresSpace = WinGetPS (hwnd); 

/*** Obtain information on Courier font. ************************************* / / 


GpiQueryFonts 

(HPresSpace, /* Handle to presentation space. */ 
QF_PRIVATE, /* Enumerate private fonts. */ 
"Courier", /* Font face name. */ 
&NumberStructs, /* Number of FONTMETRICS structures returned. */ 
(long)sizeof (FONTMETRICS),/* Length of structure for EACH font. */ 
&Metrics); /* Address of FONTMETRICS structure(s). */ 


/*** Store font information in global variables. *****************************/ 

yCharTot = (SHORT)Metrics.IMaxBaselineExt; 
yCharDesc = (SHORT)Metrics.IMaxDescender; 

FontAttributes.usRecordLength = sizeof (FontAttributes); 

FontAttributes.fsSelection = Metrics.fsSelection; 

FontAttributes.IMatch = Metrics.IMatch; 

strcpy (FontAttributes.szFacename,Metrics.szFacename); 

FontAttributes.idRegistry = Metrics.idRegistry; 

FontAttributes.usCodePage = Metrics.usCodePage; 

FontAttributes.IMaxBaselineExt = Metrics.IMaxBaselineExt; 

FontAttributes.lAveCharWidth = Metrics.lAveCharWidth; 

FontAttributes.fsType = FATTR_TYPE_FIXED; 

FontAttributes.fsFontUse = 0; 

/*** Release presentation space. *********************************************/ 
WinReleasePS (HPresSpace); 

return FALSE; 

} /* end Create */ 


• Figure 3.17: 

The function Create from the example program 





A single call to the function GpiQueryFonts can supply information 
on any number of fonts that have been loaded (from one or more font 
files), as well as information on the default system font. The function 
Create, however, requests information only on the first available 
Courier font. This font is specified by passing the string // Courier // as 
the third parameter, which supplies the face name of the font; also, the 
variable pointed to by the fourth parameter is assigned a value of 1, 
which requests information on only a single font. Accordingly, Gpi¬ 
QueryFonts returns information on the first available font that matches 
the face name Courier. 

(As a program enhancement, you could read information on all 
available Courier fonts, and then select—or allow the user to select— 
the most appropriate font. Note that the function GpiQueryFonts 


GpiLoadFonts 

Purpose: 

Loads one or more fonts from a font file. 

Prototype: 

BOOL APIENTRY GpiLoadFonts 
(hab hab, Anchor block handle. 

psz pszFiiename) ; A NULL-terminated string containing 

the full path name of the file 
containing the definition of the fonts to 
be loaded (the file has the .FON 
extension). 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Related Function: 

GpiQueryFonts (Figure 3.20) 

• Figure 3.18: 

The GpiLoadFonts Presentation Manager function 
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returns the number of remaining fonts for which information has not 
been read, thus allowing you to determine the total number of fonts 
available that match the specified face name. You could dynamically al¬ 
locate a temporary block of memory from the operating system to hold 
the font information.) 

The information supplied by GpiQueryFonts is received in the fields 
of one or more FONTMETRICS structures (defined in OS2DEF.H). Since 
the example program requests information on only a single font, it allo¬ 
cates and passes the address of a single FONTMETRICS structure 
(Metrics). The program uses the font information obtained from Gpi¬ 
QueryFonts for two basic purposes. 


WinGetPS 

Purpose: 

Obtains a cache presentation space. 

Prototype: 

HPS APIENTRY WinGetPS 

(hwnd hwnd) ; Handle of the window to obtain a 

presentation space. 

Return Value: 

The handle of the presentation space; returns NULL if an 
error occurs. 

Notes: 

The presentation space must be released by calling Win- 
ReleasePS. 

Related Functions: 

WinReleasePS (Figure 3.22) 

• Figure 3.19: 

The WinGetPS Presentation Manager function 
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GpiQueryFonts 

Purpose: 

Returns information on one or more of the fonts that are cur- 

rently available. 

Prototype: 

LONG APIENTRY 

GpiQueryFonts 

(HPS hps, 

Presentation space handle. 

ULONG flOptions, 

A flag indicating the type of 
fonts to be queried; you can 
pass one or both of the 
following values (combined 
with the 1 operator): 

Value Type of Font 

QF_PUBLIC System font 

QFJPRIVATE Fonts loaded by the 

application (by calling 
GpiLoadFonts) 

PSZ pszFacename 

A string containing the font face 
name (such as "Courier" or 
"Courier Italic"); information 
will be retrieved only for fonts 
that match this name. Passing 
the value NULL causes the 
system to return information for 
all fonts, regardless of their face 
names. 

PLONG pcFonts, 

Points to a LONG variable 
containing the number of fonts 
for which information is to be 
retrieved. 

LONG cbMetrics, 

Specifies the length of the 
structure to receive the 
information for each font; to 
receive all available 
information, this value should 
be sizeof (FONTMETRICS); 
no more data are supplied for 
each font than the value 
specified by this parameter. 


® Figure 3.20: 

The GpiQueryFonts Presentation Manager function 



# 120 Programmer's Guide to the OS/2 Presentation Manager 


— — - --— - — 

pfontmetrics pfmMetrics) ; Points to the FONTMETRICS 

structure(s) to receive the font 
information (this structure is 
defined in OS2DEF.H); the 
total size of the receiving buffer 
must be the value of *pcFonts 
multiplied by cbMetrics. 

Return Value: 

The number of matching fonts for which information was 
not returned. A return value of zero indicates that informa¬ 
tion was supplied for all matching fonts (it does not indicate 
an error); a nonzero value indicates that you can obtain in¬ 
formation on additional fonts by passing a larger value in the 
pcFonts parameter. 

Notes: 

By examining the data returned by this function, you can 
choose the font most suitable for the application. To select 
the desired font, you must call the functions GpiCreateLog- 
Font and GpiSetCharSet. 

Related Functions: 

GpiLoadFonts (Figure 3.18) 

GpiCreateLogFont (Figure 3.26) 

GpiSetCharSet (Figure 3.27) 


• Figure 3.20: 

The GpiQueryFonts Presentation Manager function (continued) 

First, it saves the value for the total character height (supplied in the 
IMaxBaselineExt field of Metrics) in the global program variable 
yCharTot, and the value for the height of the character descenders (sup¬ 
plied in the IMaxDescender field) in the variable yCharDesc. These 
dimensions will be used each time the WM_PAINT message is received 
by the client window, and they are illustrated in Figure 3.21. Note that 
in the example program, these dimensions are given in screen pixels. By 
employing the actual dimensions used to display the font on the current 
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display device, the routine that processes the WM_PAINT message can 
properly position the lines of text within the window and can maintain 
a consistent screen appearance regardless of the current graphics 
resolution. 

Second, the function Create uses the font information it has obtained 
from GpiQueryFonts to assign appropriate values to the fields of a 
FATTR structure (FontAttributes). As you will see in the section describ¬ 
ing the WM_PAINT message, the FATTR structure is used to specify the 
current font that is to be employed for displaying characters. Note that 



@ Figure 3.21: 

The character dimensions obtained from GpiQueryFonts 
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since the font-management functions GpiLoadFonts and GpiQuery- 
Fonts need be called only once, they are placed in the WMCREATE 
routine, which is invoked a single time during window initialization. 
The information stored from the call to GpiQueryFonts remains valid 
during the entire program. The other two font-management functions 
used in the program (GpiCreateLogFont and GpiSetCharSet) must be 
called each time a presentation space is obtained for updating the win¬ 
dow. These functions are thus placed in the function that processes 
WM_CHAR messages (Paint, described later in the chapter). 

Finally, since a cache presentation space must be released before the 
program returns from processing the WM_CREATE message. Create 
calls the Presentation Manager function WinReleasePS (Figure 3.22) 
immediately before returning, to release the presentation space 
provided by WinGetPS. 


WinReleasePS 

Purpose: 

Releases the presentation space obtained through WinGetPS. 
Prototype: 

BOOL APIENTRY WinReleasePS 

(hps hps); Handle of the presentation space returned 

by WinGetPS. 

Return Value: 

TRUE if the function is successful, and FALSE if an error 
occurred. 

Related Functions: 

WinGetPS (Figure 3.19) 

® Figure 3.22: 

The WinReleasePS Presentation Manager function 
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The WM„SIZE Message 

The system sends the WM_SIZE message (Figure 3.23) to the 
client window procedure immediately after the window is created ( after 
the WMCREATE message), and subsequently each time the window 
changes size. The example program takes advantage of this message to 
maintain a record of the current vertical dimension of the client win¬ 
dow. The WM_SIZE message is processed by the function Size, listed in 
Figure 3.24. This function extracts the current vertical dimension of the 
client window from the high-order word of the mp2 parameter and 
stores it in the variable yWin. Note that this dimension, like the font 
dimensions collected during window initialization, is also given in 
screen pixel units. The vertical window dimension will subsequently be 
used by the routine that processes the WM_PAINT message. This value 


WM_SIZE 


Purpose: 


Sent by the system to 

a window whenever its size changes. 

Parameters: 


MPARAM mpl 

low-order word: 

Previous width. 

high-order word: 

Previous height. 

MPARAM mp2 

low-order word: 

Current width. 

high-order word: 

Current height. 

Return Value: 


FALSE. 



• Figure 3.23: 

The WM_SIZE Presentation Manager message 
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will be used in conjunction with the font dimensions to calculate the 
number of lines that can be displayed within the window and the cor¬ 
rect placement of these lines. (Note that when the window is increased 
in size, thereby invalidating a section of screen data, the WM_SIZE mes¬ 
sage is sent before the WM PAINT message.) 


MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

/*** obtain vertical dimension of client window. ****************************/ 
yWin = SHORT2 FROMMP (mp2) ; 

return FALSE; 

} /* end Size */ 


• Figure 3.24: 

The Size function of the example program 


The WM_PAINT Message 

As explained in Chapter 2, the WM_PAINT message (Figure 2.19) 
is sent to the client window procedure whenever any portion of the 
window data becomes invalid and requires repainting. This message is 
also sent by WinCreateStdWindow when the window is first created. 
In review, the following three messages processed by the example pro¬ 
gram are sent during window creation, in the order listed: 

1. WM_CREATE 

2. WM_SIZE 

3. WMJPAINT 

The WMJPAINT message is processed by the function Paint, listed in 
Figure 3.25. Like the previous version of the example program, the cur¬ 
rent version calls WinBeginPaint and WinEndPaint to obtain and 
release a presentation space. Once the current version has obtained 
a presentation space, however, it calls two Presentation Manager 
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MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

register int Line; /* Loop counter. */ 

HPS HPresSpace; /* Presentation space handle. */ 

RECTL Rect; /* Window coordinates, in pixels. */ 

SHORT StopLine; /* Last line to paint. */ 

POINTL Start; /* Starting position to print string. */ 

SHORT LineLength; /* Length of each line displayed. */ 

HPresSpace = WinBeginPaint 

(hwnd, /* Window handle. */ 

0, /* Handle of PS to have clipping region set. */ 


0); /* Address of variable to set to update region.*/ 

/*** create a logical font for this presentation space. **********************/ 
GpiCreateLogFont 


(HPresSpace, 

/* 

Presentation space 

handle. 

V 

(PSTR8)NULL, 

/* 

Logical font name; 

none. 

V 

ID_COURIER, 

/* 

Local font ID. 


*/ 

&FontAttributes); 

/* 

Struct, specifying 

font from GpiQueryFonts. 

*/ 


/*** Make the logical font the current character set. ************************/ 


GpiSetCharSet 


(HPresSpace, 

/* Presentation space handle. 

V 

ID_COURIER); 

/* Local font ID. 

*/ 

WinQueryWindowRect 

/* Get dimensions of window. 

*/ 

(hwnd, 

/* Window handle. 

V 

&Rect); 

/* Structure to receive coordinates. 

V 

WinFillRect 

/* Erase window. 

V 

(HPresSpace, 

/* Presentation space handle. 

V 

&Rect, 

/* Structure containing window coordinates. 

*/ 

CLR_WHITE)? 

/* Color to use (white). 

V 

Set foreground color 

used by 'GpiCharStringAt'. *************************/ 

GpiSetColor 



(HPresSpace, 

/* Presentation space handle. 

V 

CLR BLACK)? 

/* Color to use; black. 

V 


/*** calculate last line to fit in client window. ****************************/ 
StopLine = min (LastLine, yWin / yCharTot); 

/*** Print lines from beginning of file within client window. ****************/ 
Start.x = 0; 

for (Line = 0, Start.y = yWin - yCharTot + yCharDesc; Line <= StopLine; 
-f+Line, Start.y -= yCharTot) 

{ 

if ((LineLength = GetLineLength (Line)) == 0) 
continue; 

GpiCharStringAt /* Prints string at given position. */ 

(HPresSpace, /* Presentation space handle. */ 


• Figure 325: 

The function Paint of the example program 
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&Start, /* Structure containing starting position.*/ 

(LONG)LineLength, /* Number of characters to print. */ 

GetLineAddr (Line));/* Address of line. */ 

WinEndPaint (HPresSpace); 
return FALSE; 

} /* end Paint */ 

® Figure 3.25: 

The function Paint of the example program (continued) 

font-management functions that cause the system to use the Courier 
font loaded by the Create function rather than the proportionally 
spaced default system font. 

First, Paint calls the GpiCreateLogFont function (Figure 3.26), which 
informs the system which font the program is going to use. This func¬ 
tion creates what is termed a logical font definition. The specified font 
must be either the default system font or a font that has been previously 
loaded by GpiLoadFonts. The program specifies the desired Courier 
font by passing as the fourth parameter the address of the FATTR struc¬ 
ture (&FontAttributes) that was previously assigned values in the Cre¬ 
ate function. The program also passes an identifier (the value 
ID COURIER, defined within the program), which will be used in the 
next function call (to GpiSetCharSet) to refer to the logical font that has 
been defined. 

Second, the program calls the GpiSetCharSet function (Figure 3.27) 
to cause the system to begin using the logical font defined by the call to 
GpiCreateLogFont. The program specifies the desired logical font by 
passing the same identifier (ID_COURIER) that it passed to GpiCreate¬ 
LogFont. Once the program has called GpiSetCharSet, all subsequent 
character output will use the newly defined font, until the presentation 
space is released. (Note that the new font is employed only for the cur¬ 
rent presentation space, the handle of which was passed as the first 
parameter to both GpiCreateLogFont and GpiSetCharSet.) 

Once the appropriate font has been established, the Faint function 
erases the contents of the window using the functions WinQuery- 
WindowRect and WinFillRect. Since the current version of the example 
program needs to fill the window with evenly spaced lines from the file, it 
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GpiCreateLogFont 

Purpose: 


Creates a logical definition of a font. 

Prototype: 


BOOL APIENTRY 

GpiCreateLogFont 

(HPS hps, 

Handle of the presentation space for which 
the font is to be defined. 

PSTR8 pchName, 

Pointer to a logical font name, which can be 
used to identify the logical font; you can 
assign any name consisting of up to eight 
characters. 

LONG lcid, 

The value that will be used to identify the 
logical font; you can supply a value between 

1 and 254; the value must not already refer 
to a font or bitmap; when you subsequently 
call GpiSetCharSet to cause the system to 
use the font, you must pass this same value 
(as the second parameter). 

PFATTRS pfat); 

Pointer to a FATRS structure (defined in 
OS2DEF.H) that defines the attributes of the 
logical font that is to be created; note that if 
there is no font that matches the attributes 


exactly, the system uses the font, of those 
available, that most closely matches the 
requirements; you can obtain the attributes 
for any avaiable font by calling 

GpiQueryFonts. 

Return Value: 


TRUE if the function was successful, or FALSE if an error 

occurred. 



• Figure 3.26: 

The GpiCreateLogFont Presentation Manager function 
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Notes: 

To define a logical font using this function, the font must al¬ 
ready have been loaded from a font file (by calling GpiLoad- 
Fonts). Alternatively, if the face name in the FATTR structure 
pointed to by pfat is NULL, and all of the attributes except 
the code page are set to zero, the system default font is 
selected in the specified code page. After calling GpiCreate- 
LogFont, you must call GpiSetCharSet to force the system to 
start using the font. 

Related Functions 

GpiLoadFonts (Figure 3.18) 

GpiQueryFonts (Figure 3.20) 

GpiSetCharSet (Figure 3.27) 


® Figure 3.26: 

The GpiCreateLogFont Presentation Manager function (continued) 

displays each line using the function GpiCharStringAt (Figure 3.28), 
which allows you to print a line at specific position within the window. 
(WinDrawText, used in the previous version, justifies text within a given 
rectangle, but does not place the text at an absolute location.) 

Before calling GpiCharStringAt to display the file lines, however, the 
function Paint performs several preliminary tasks. First, it calls GpiSet- 
Color (Figure 3.29) to set the color that GpiCharStringAt uses to draw 
the text. The program specifies the color black (CLR BLACK) to provide 
an optimal contrast to the white background created by WinFillRect. 

Second, the function Paint uses the data maintained by the other two 
message-handling routines to calculate the number of lines that can be 
displayed within the window and the starting position for the first line 
of text. The number of lines to be displayed (StopLine) is calculated 
using the following expression: 


StopLine = min (LastLine, yWin / yCharTot); 


The macro min is defined in the C header file STDLIB.H. Since yWin is 
the total number of vertical pixels in the window, and yCharTot is the 
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GpiSetCharSet 

Purpose: 

Sets the current character set used for displaying textual data 

within the specified presentation space. 

Prototype: 

BOOL APIENTRY GpiSetCharSet 

(hps hps , Handle of the presentation space for which 

the character set is to be set. 

long icid) ; The identifier for the character set, which 

can be one of the following values: 

Identifier Meaning 

LCID_DEFAULT The default character 

set (you can use this 
option to restore the 
default font after 
temporarily using a 
locally loaded font) 

1 to 254 A logical font defined 

by GpiCreateLogFont; 
you must pass the same 
identifier within this 
range that was passed 
to GpiCreateLogfont 
(in the third parameter) 

Return Value: 

TRUE if the function was successful, or FALSE if an error 

occurred. 

Related Functions: 

GpiCreaieLogFont (Figure 3.26) 


« Figure 3.27: 

The GpiSetCharSet Presentation Manager function 
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GpiCharStringAt 


Purpose: 

Draws a line of text at a specified starting position. 
Prototype: 

LONG APIENTRY GpiCharStringAt 
(hps hps , Handle of the presentation space. 

ppointl pptistart , Pointer to a POINTL structure (defined 
below) containing the starting position. 
long cchstring, Number of characters in the string to 

be displayed. 

pch pchstring) ; Address of character string to be 

displayed. 

Structure: 

typedef struct __POINTL 
1 

LONG x; 

LONG y; 

1 

POINTL; 

Return Value: 

Returns a nonzero value if the function is successful, and 
GPI_ERROR if an error occurs. 

Notes: 

This function is equivalent to calling these two functions: 
GpiMove (hps, pptlStart) 

GpiCharString (hps, cchString, pchString) 

When the function has completed drawing the string, it 
moves the current pointer to the end of the string. 

Related Functions: 

GpiMove (Figure 11.22) 

GpiCharString 

• Figure 3.28: 

The GpiCharStringAt Presentation Manager function 
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total number of vertical pixels required for a single line of text, Stop- 
Line is assigned the total number of complete lines (integer division 
truncates a partial line) that fit within the window, or the value Last- 
Line if the file does not contain sufficient lines to fill the window. 

GpiCharStringAt must be passed the address of a POINTL structure 
(defined in Figure 3.28) specifying the starting point of the line of text. 
Positions within a window are specified according to a coordinate sys¬ 
tem that has its origin at the lower left corner of the window. Accord¬ 
ingly, the point (x=0, y=0) represents the lower-leftmost pixel in the 
window, and coordinates increase moving up and to the right. This 
coordinate system is illustrated in Figure 3.30 (the value xWin is the 
horizontal size of the window that is also supplied by the WMSIZE 
message, but is not used until Chapter 4). GpiCharStringAt places the 
lower left pixel—on the baseline—of the first character in the string at 
the specified starting point (this position is illustrated in Figure 3.21). 


GpiSetColor 


Purpose: 


Sets the foreground color used by Gpi functions such as Gpi¬ 
CharStringAt. 

Prototype: 


BOOL APIENTRY 

(HPS hps, 

LONG IColor); 

GpiSetColor 

Handle of the presentation space. 

The color; you can select any of the color 
values listed in Figure 2.23 (the description 
of WinFillRect). 

Return Value: 


TRUE if the function is successful, FALSE if an error occurs. 


• Figure 3.29: 

The GpiSetColor Presentation Manager function 
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The program calculates the starting point of the first line using the 
following expressions: 

Start.x = 0; 

Start.y = yWin - yCharTot + yCharDesc; 


These expressions place the first line at the top of the window and jus¬ 
tify the string at the left window edge. Finally, the vertical starting point 
is decremented after each line is displayed using the following expres¬ 
sion within the for statement: 

Start.y -= yCharTot; 

This expression places each subsequent line from the file on the next 
lower line position within the window. 

The GpiCharStringAt function is passed the length of each line. If a 
line is longer than will fit within the window, the Presentation Manager 
automatically clips the portion that falls outside the current window 
dimensions (that is, the inappropriate points do not cause an error but 
are simply not displayed). In general, when calling Presentation 
Manager display functions, you can safely specify coordinates outside 



• Figure 330: 

The coordinate system used for specifying points within a window 
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the dimensions of the window; only the portions of a figure within the 
window (if any) will be visible. 

You may also have noticed that the for loop seemingly attempts to 
print one more line than will fit within the window (Line ranges from 0 
up to and including StopLine). Remember, however, that StopLine is 
the number of complete lines that can fit within the window. By printing 
StopLine + 1 lines, the portion of any partial line that falls within the 
window will be displayed; the section of this partial line that falls out¬ 
side of the window is clipped. 

Note that the current display routine always repaints the entire win¬ 
dow. More accurately, the program only attempts to repaint the entire 
screen; actually, the presentation space provided by WinBeginPaint 
automatically clips all data outside the current invalid window region; 
ineffectual calls to GpiChar String At, however, waste time. The pro¬ 
gram in Chapter 4 enhances the efficiency of the display routine by 
redrawing only the invalid section of the client window. 


• ENHANCEMENTS 

This section offers several suggestions for enhancing the version 
of the example program presented in this chapter. These enhancements 
are beyond the scope of the book, and are not developed in subsequent 
chapters. You can use them as exercises in Presentation Manager 
programming and to increase the usefulness of the example program. 

First, one of the major limitations of the example program is the 
restriction on file size. You cannot load a file that is larger than 50,000 
bytes, and you cannot increase the file size beyond the maximum heap 
size (the segment containing the heap has a maximum size of 64 
kilobytes). To overcome this limitation and yet continue to use the 
Presentation Manager memory-allocation functions, your program can 
manage more than one heap. The following are some suggested steps 
for greatly increasing the maximum file size by using multiple heaps: 

1. Create an initial heap (WinCreateHeap) and begin allocating 
memory (WinAJlocMem) within this heap for all lines loaded 
from the file or inserted by the user (inserting lines is discussed 
in later chapters). 
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2. When WinAllocMem returns NULL and WinGetLastError 
returns PMERR_HEAP_MAX_SIZE_REACHED, indicating that 
the maximum heap size has been attained, create another heap 
(WinCreateHeap) and begin allocating from the new heap. Since 
LineTable contains the complete far address of each line, the fact 
that lines are contained in multiple heaps is invisible to the pro¬ 
gram. Repeat this step as necessary. 

3. As you will see in subsequent chapters, when the user adds or 
deletes data, you must deallocate the memory block containing 
the current line by calling WinFreeMem. This function requires 
the handle to the appropriate heap. The selector of the far ad¬ 
dress contained in LineTable can be used to uniquely identify 
the specific heap (each heap has a unique segment selector). You 
can find the corresponding heap handle in a lookup table you 
maintain, which contains selector/handle pairs. 

Note that as memory blocks are allocated and deallocated, the pro¬ 
gram should limit the number of partially filled heaps. Alternatively, 
you could possibly attain greater efficiency by completely bypassing 
the Presentation Manager heap functions, and writing your own heap- 
management routines; the raw memory for your heap could be ob¬ 
tained directly from the operating system through the DosAllocHuge 
function, which allocates blocks of memory consisting of more than one 
segment. 

As a second possible enhancement to the example program, you 
could increase the efficiency of the routine that reads data from the file 
and extracts individual lines. For simplicity, this routine calls the stand¬ 
ard high-level C function fgets to extract each line from the file. Alterna¬ 
tively, you could read the entire file (or 64-kilobyte blocks of the file, if 
the file is longer than this size) directly into a temporary buffer. You can 
dynamically allocate this buffer from the operating system though the 
DosAllocSeg OS/2 function, and you can read the file directly into the 
buffer with a single call to the DosRead system routine (you must open 
and close the file using DosOpen and DosClose). You can then write 
your own routine to efficiently extract individual lines and copy them 
into the heap. (If you have written your own heap-management 
module, you may even be able to leave the lines in the buffer into which 
they were initially read, eliminating the copy operations!) 
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• CONCLUSION 

The MAKE file for preparing the current version of the example 
program is provided in Figure 3.31, the definition file is given in Figure 
3.32, and the complete program listing is in Figure 3.33. 

This chapter has introduced the basic data structures and routines for 
reading the file and managing the file data within the internal program 
buffer. Later chapters will add features for inserting and deleting data 
in the file buffer. 

The chapter has also presented a basic routine for displaying multi¬ 
ple evenly spaced lines within the window. Subsequent chapters will 
add features that allow the program to scroll the contents of the win¬ 
dow and to force the updating of specific window areas. 


# Figure 3.31 

# This MAKE file prepares the program of Figures 3.32 and 3.33. 

# 

FIG3_33.OBJ : FIG3 33 .C 

cl /W2 /c /Zp /G2ws FIG3_33.C 

FIG3_33.EXE : FIG3 33.OBJ FIG3 32.DEF 

link /NOD FIG3_33.OBJ,, NUL, OS2.LIB SLIBCE.LIB, FIG3_32.DEF 


• Figure 331: 

A MAKE file for preparing the example program 

; Figure 3.32 

; Linker definition file for the program listed in Figure 3.33 

NAME FIG3 33 

PROTMODE 

HEAPSIZE 1024 

STACKSIZE 8192 

EXPORTS WndProc 



• Figure 332: 

A linker definition file for preparing the example program 
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Figure 3.33 

Version 2 of the Presentation Manager text editor example program. 

This version performs the following additional tasks: 

o Obtains the name of a text file from the command line, 
o Reads the file into dynamically allocated memory. 

o Displays as many lines from the beginning of the file as will fit 
within the client window. 


#define INCL_GPI 
#define INCL_WIN 
#include <0S2.H> 
#include <STDIO.H> 

#include <PROCESS.H> 
#include <10.H> 
#include <STRING.H> 
#include <STDLIB.H> 


/* Include all Gpi... function declarations. 
/* include all Win... function declarations. 

/* C library header files: 


/*** Window procedure declaration. *******************************************/ 

MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 

/*** Declarations / definitions for file- and buffer-management module. ******/ 

^define LINEBUFSIZ 255 /* Size of buffer for holding lines. */ 

#define ERROPEN 1 /* Error: opening file. */ 

^define ERRTOOBIG 2 /* Error: file too large. */ 

#define ERRMAXLINES 3 /* Error: maximum file lines exceeded. */ 

#define ERRALLOC 4 /* Error: heap allocation. */ 


void Buflnit (void); /* Initializes buffer-management module. */ 
char *ErrorMessage (int ErrorNumber); /* Returns error message string. */ 
int ReadFile (char *FileName); /* Reads file into editor buffer. */ 
SHORT GetLineLength (int Line); /* Gets length of line in buffer. */ 
PCH GetLineAddr (int Line); /* Gets address of line in buffer. */ 


int LastLine = -1; 
HHEAP HHeap = NULL; 


/* Number of last line in buffer. 
/* PM heap handle. 


/*** Utility function declarations. ******************************************/ 

void ErrorQuit (char ^Message); /* Print error message, end program. */ 

void Quit (int ErrorCode); /* Terminate the PM program. */ 

/*** Global variables. ********************************^ 


HWND HFrame; 

HAB HAncBlk; 

HMQ HMesQue; 

void main (int argc, char *argv[]) 


/* Handle to main frame window. 
/* Handle to anchor block. 

/* Message queue handle. 


@ Figure 3.33: 

The source codefile for the example program 
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{ 


int 

ReadError = 0; 

/* 

Error occurred reading file. 

*/ 

int 

UsageError = 0; 

/* 

No file name given on command line. 

*/ 

HWND 

HClient; 

/* 

Handle to main client window. 

*/ 

QMSG 

QueMess; 

/* 

Message structure. 

*/ 

ULONG CtlData = 

/* 

Control windows to include. 

*/ 


FCF MINMAX 

/* 

Minimize/maximize box. 

V 


FCF SIZEBORDER 

/* 

Wide sizing border. 

*/ 


FCF SHELLPOSITION 

/* 

Make window visible on screen. 

*/ 


FCF SYSMENU 

/* 

System menu. 

*/ 


FCF TASKLIST 

/* 

Display program name in Task Manager. 

V 


FCF TITLEBAR; 

/* 

Title bar. 

*/ 


/*** Initialize the buffer-management module. ********************************/ 
Buflnit (); 

/*** Test for file name on command line. *************************************/ 

if (argc < 2) 

UsageError = 1; 

else 

/*** Read file into editor buffer. *******************************************/ 
ReadError = ReadFile (argv [1])? 

/*** Presentation Manager initializations. ***********************************/ 


HAncBlk = Winlnitialize (0); 

HMesQue = WinCreateMsgQueue 

/* Initialize PM system for process. 

(HAncBlk,0); /* Create a message queue. 

*/ 

*/ 

WinRegisterClass 

/* 

Register procedure for main window. 

*/ 

(HAncBlk, 

/* 

Anchor block handle. 

V 

"MAIN", 

/* 

Window class name. 

V 

WndProc, 

/* 

Window procedure associated w/ class. 

V 

0L, 

/* 

Class style. 

V 

0) ? 

/* 

Extra storage bytes. 

V 

HFrame = WinCreateStdWindow 

/* 

Create parent window. 

V 

(HWND DESKTOP, 

/* 

Parent window handle. 

V 

WS VISIBLE, 

/* 

Frame window style. 

V 

(ScCtlData, 

/* 

Address of control data. 

V 

"MAIN", 

/* 

Client window class name. 

*/ 

": PM Text Editor", 

/* 

Text for title bar. 

*/ 

0L, 

/* 

Client window style. 

*/ 

o, 

/* 

Resource module handle. 

*/ 

o, 

/* 

Resource identification. 

*/ 

SHClient); 

/* 

Address to receive client window hand. 

*/ 


/*** Test for file error conditions. ****************************************/ 
if (UsageError) 

ErrorQuit ("Must specify file name."); 
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/*** 


if (ReadError) 

ErrorQuit (ErrorMessage (ReadError)); 

Main message-handling loop. *********************************************/ 


while (WinGetMsg /* Get messages until WM_QUIT. */ 

(HAncBlk, /* Anchor block handle. */ 

&QueMess, /* Address of message structure. */ 

0, /* Window filter. */ 

0, /* First message identifier. */ 

0)) /* Last message identifier. */ 

WinDispatchMsg (HAncBlk,&QueMess); /* Dispatch messages. */ 


/*** Relinguish Presentation Manager resources and terminate application. ****/ 
Quit (0); 

} /* end main */ 


/*** window procedure and subroutines. ***************************************/ 

MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


static SHORT yCharTot; /* Total height of characters. */ 

static SHORT yCharDesc; /* Height of character descenders. */ 

static SHORT yWin; /* Vertical size of window in window coord. */ 

static FATTRS FontAttributes; /* Stores font attributes from GpiQueryFonts. */ 

#define ID_COURIER 99L /* Local font ID. */ 

MRESULT EXPENTRY WndProc 

(HWND hwnd, /* Window handle. */ 

USHORT msg, /* The message. */ 

MPARAM mpl, /* Message-specific information. */ 

MPARAM mp2) /* Message-specific information. */ 

( 

switch (msg) 

( 

case WM_CREATE: /* Message sent when window is first created. */ 

return Create (hwnd, msg, mpl, mp2); 

case WM_PAINT: /* Message sent when window data is invalid. */ 

return Paint (hwnd, msg, mpl, mp2); 

case WM_SIZE: /* Message sent whenever window changes size. */ 

return Size (hwnd, msg, mpl, mp2); 


default: /* Perform default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2) ? 
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} /* end switch */ 


} /* end WndProc */ 

/*** Subroutines called by window procedure. *********************************/ 


MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

HPS HPresSpace; /* Presentation space handle. */ 

FONTMETRICS Metrics; /* Structure to hold font dimensions. */ 

LONG NumberStructs =1; /* Number of structures from GpiQueryFonts. */ 

/*** Load Courier monospace font. ********************************************/ 
GpiLoadFonts 

(HAncBlk, /* Anchor block handle. */ 

"\\0S2\\DLL\\C0URIER.F0N"); /* Full path name of font file. */ 


/*** obtain a handle to a presentation space. ********************************/ 
HPresSpace = WinGetPS (hwnd); 

/*** Obtain information on Courier font. *************************************/ 


GpiQueryFonts 

(HPresSpace, /* Handle to presentation space. */ 
QF_PRIVATE, /* Enumerate only private fonts. */ 
"Courier", /* Font face name. */ 
SeNumberStructs, /* Number of FONTMETRICS structures returned. */ 
(long)sizeof (FONTMETRICS),/* Length of structure for EACH font. */ 
StMetrics) ; /* Address of FONTMETRICS structure(s) . */ 


/*** store font information in global variables. *****************************/ 

yCharTot = (SHORT)Metrics.IMaxBaselineExt; 
yCharDesc = (SHORT)Metrics.IMaxDescender; 

FontAttributes.usRecordLength = sizeof (FontAttributes); 

FontAttributes.fsSelection = Metrics.fsSelection; 

FontAttributes.IMatch = Metrics.IMatch; 

strcpy (FontAttributes.szFacename,Metrics.szFacename); 

FontAttributes.idRegistry = Metrics.idRegistry; 

FontAttributes.usCodePage = Metrics.usCodePage; 

FontAttributes.IMaxBaselineExt = Metrics.IMaxBaselineExt; 

FontAttributes.lAveCharWidth = Metrics.lAveCharWidth 7 
FontAttributes.fsType = FATTR_TYPE_FIXED; 

FontAttributes.fsFontUse = 0; 

/*** Release presentation space. *********************************************/ 
WinReleasePS (HPresSpace); 

return FALSE; 

} /* end Create */ 
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MRESULT EXPENTRY Paint (HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


{ 

register int Line; 

/* Loop counter. 

*/ 

HPS HPresSpace; 

/* Presentation space handle. 

*/ 

RECTL Rect; 

/* Window coordinates, in pixels. 

V 

SHORT StopLine; 

/* Last line to paint. 

V 

POINTL Start; 

/* Starting position to print string. 

*/ 

SHORT LineLength; 

/* Length of each line displayed. 

*/ 

| HPresSpace = WinBeginPaint 


| (hwnd, 

/* Window handle. 

*/ 

i 0, 

/* Handle of PS to have clipping region set. 

*/ 

| 0) ; 

/* Address of variable to set to update region, 

*/ 

/*** Create a logical font for this presentation space. **********************/ 

GpiCreateLogFont 



(HPresSpace, 

/* Presentation space handle. 

*/ 

(PSTR8)NULL, 

/* Logical font name; none. 

*/ 

ID COURIER, 

/* Local font ID. 

V 

&FontAttributes); 

/* Struct, specifying font from GpiQueryFonts. 

V 

/*** Make the logical font the current character set. ************************/ 

GpiSetCharSet 



(HPresSpace, 

/* Presentation space handle. 

*/ 

ID_COURIER); 

/* Local font ID. 

V 

WinQueryWindowRect 

/* Get dimensions of window. 

*/ 

(hwnd, 

/* Window handle. 

V 

&Rect); 

/* Structure to receive coordinates. 

V 

WinFillRect 

/* Erase window. 

V 

(HPresSpace, 

/* Presentation space handle. 

V 

&Rect, 

/* Structure containing window coordinates. 

V 

CLR WHITE); 

/* Color to use (white). 

V 

/*** set foreground color used by 'GpiCharStringAt'. *************************/ 

GpiSetColor 



(HPresSpace, 

/* Presentation space handle. 

*/ 

CLR_BLACK) ; 

/* Color to use: black. 

V 

/*** Calculate last line to 

fit in client window. ****************************/ 

StopLine = min (LastLine, yWin / yCharTot); 


/*** print lines from beginning of file within client window. ****************/ 

Start.x = 0; 



for (Line = 0, Start.y 

= yWin - yCharTot + yCharDesc; Line <= StopLine; 


++Line, Start.y -= 

yCharTot) 


{ 

if ( (LineLength = 

GetLineLength (Line) ) == 0) 


continue ; 



GpiCharStringAt 

/* Prints string at given position. 

*/ 

(HPresSpace, 

/* Presentation space handle. 

*/ 
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SStart, /* Structure containing starting position.*/ 

(LONG)LineLength, /* Number of characters to print. */ 

GetLineAddr (Line));/* Address of line. */ 

} 

WinEndPaint (HPresSpace); 
return FALSE; 

} /* end Paint */ 


MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

/*** Obtain vertical dimension of client window. ****************************/ 
yWin = SH0RT2 FROMMP (mp2) ; 

return FALSE; 

) /* end Size */ 


/*** Buffer— and file—management module **************************************/ 


#define MAXLINES 4096 /* Maximum number of lines in buffer. */ 

static struct /* Stores information on each line. */ 

{ 

PCH LineAddress; /* Far address of block containing line. */ 

unsigned char LineLength; /* Length of line (includes \n and \0). */ 

} 

LineTable [MAXLINES]; 

static char LineBuffer [LINEBUFSIZ]; /* Temporary line buffer. */ 

static unsigned LineSelector; /* Selector for 'LineBuffer'. */ 

static unsigned LineOffset; /* Offset for 'LineBuffer'. */ 

static SEL HeapSelector; /* Selector of heap segment. */ 

void Buflnit (void) /* Initializes the buffer-management module. */ 

{ 

PCH FarPtr; 


/*** Obtain selector and offset of temporary line buffer. ********************/ 

FarPtr = (char far *)LineBuffer; 

LineSelector = SELECTOROF (FarPtr); 

LineOffset = OFFSETOF (FarPtr); 

} /* end Buflnit */ 


char *ErrorMessage /* Returns a string that describes an error code. */ 

(int ErrorNumber) /* The error code. */ 

{ 

static char *MessageTable [] = 
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{ 

"no error", 

"file open failure", 

"file too large", 

"maximum lines exceeded", 

"heap memory allocation failed", 
"unidentified error" 


if (ErrorNumber >= sizeof (MessageTable) / sizeof (char *)) 

ErrorNumber = sizeof (MessageTable) / sizeof (char *) - 1; 

return MessageTable [ErrorNumber]; 

} /* end ErrorMessage */ 


ReadFile 

/* 

Reads file into editor. 

*/ 

(char *FileName) 

{ 

FILE *PtrFile; 

/* 

Name of 

file. 

V 

/* 

File stream pointer. 

V 

long FileLength; 

/* 

Size of 

file. 

V 

USHORT HeapSize; 

/* 

Size of 

allocated heap. 

V 

NPCH HeapOffset; 

/* 

Offset 

of blocks within heap. 

V 

unsigned char LineLength; 

/* 

Length 

of lines. 

*/ 

PCH FarPtr; 

/* 

Temporary far pointer. 

V 


/*** Open the file. **********************************************************/ 

if ((PtrFile = fopen (FileName,"r")) == NULL) 
return (ERROPEN); 

/*** obtain and test file length. ********************************************/ 

if ((FileLength = filelength (fileno (PtrFile))) == -1) 
return (ERROPEN); 

if (FileLength > 50000) 
return (ERRTOOBIG); 


/*** Allocate a heap to hold file lines. *** 

/* Make heap 20% larger than size of file. 
HeapSize = (USHORT)(FileLength + FileLength / 5); 

HHeap = WinCreateHeap 




*/ 


(0, 

/* 

Segment 

address: 0 means allocate 

new segment. 

V 

HeapSize, 

/* 

Initial 

heap size. 




V 

0 , 

/* 

Minimum 

increase size: 

0 means use 

default. 

V 

0, 

/* 

Minimum 

# of dedicated 

free 

lists: 

none. 

V 

0 , 

/* 

Maximum 

# of dedicated 

free 

lists: 

none. 

V 

0) 7 

/* 

Options: 

: none. 




*/ 


/*** obtain selector to heap segment. ****************************************/ 
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FarPtr = WinLockHeap (HHeap); 

HeapSelector = SELECTOROF (FarPtr); 

/*** Read each line in file into a separate block allocated from heap. *******/ 
LastLine = -1; 

while (fgets (LineBuffer,LINEBUFSIZ-1,PtrFile) != NULL) 

{ 

/*** Test for line limit — update 'LastLine'. *********************/ 
if (++LastLine >= MAXLINES) 
return (ERRMAXLINES); 

/*** Calculate length of line. *************************************/ 
LineLength = (unsigned char)strlen (LineBuffer) + 1;/* Include null*/ 

/*** insert '\n' into overlength lines. ****************************/ 
if (LineLength ==-LINEBUFSIZ - 1 && 

LineBuffer [LINEBUFSIZ - 3] != '\n') 

{ 

LineBuffer [LINEBUFSIZ - 2] = '\n'; 

LineBuffer [LINEBUFSIZ - 1] = '\0'; 

++LineLength; 

} 

/*** Allocate a block from 
HeapOffset = WinAllocMem 
(HHeap, 

LineLength)? 
if (HeapOffset == NULL) 
return (ERRALLOC); 

/*** Copy line into heap block. ************************************/ 
movedata (LineSelector,LineOffset,HeapSelector, 

(unsigned)HeapOffset,LineLength); 

/*** insert line information into the table. ***********************/ 
LineTable [LastLine].LineAddress = MAKEP (HeapSelector,HeapOffset); 
LineTable [LastLine].LineLength = LineLength; 

} 

/*** Close the file. *********************************************************/ 
fclose (PtrFile); 
return (0); 

} /* end of ReadFile */ 


SHORT GetLineLength (int Line) /* Gets length of line in buffer. */ 

{ 

if (Line < 0 || Line > LastLine) 
return 0; 

else 

/* Extract line length from table, excluding '\n' and '\0'. */ 

return LineTable [Line].LineLength - 2; 
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heap to hold the line. ******************/ 

/* Heap handle. */ 

/* Length of line to store. */ 
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} /* end GetLineLength */ 


PCH GetLineAddr (int Line) /* Gets address of buffer line. */ 

if (Line < 0 || Line > LastLine) 
return NULL; 

else 

return LineTable [Line].LineAddress; 

} /* end GetLineAddr */ 


/*** utility functions. ******************************************************/ 

void ErrorQuit /* Terminate program due to fatal error condition. */ 

(char ^Message) /* Error message to display to user. */ 

{ 

char Buffer [60]; 


sprintf (Buffer,"Program Error: %s",Message)? 


WinMessageBox 

/* Display a message box. 

V 

(HWND_DESKTOP, 

/* Handle of parent: desktop window. 

V 

HFrame, 

/* Handle of owner: frame window. 

*/ 

Buffer, 

/* Message text. 

*/ 

"PM Text Editor", 

/* Caption. 

V 

0 , 

/* Help window ID: not needed. 

*/ 

MB OK | 

/* Display an 'OK' button. 

*/ 

MB_ICONHAND); 

/* Display a hand icon. 

V 

Quit (1); 

/* Call normal termination function. 

*/ 


} /* end ErrorQuit */ 


void Quit 

(int ErrorCode) /* Process termination status. */ 

/* 

Calls Presentation Manager termination functions and ends program 
with specified error code. 

V 

{ 

if (HHeap != NULL) 

WinDestroyHeap (HHeap); 

WinDestroyWindow (HFrame); 

WinDestroyMsgQueue (HMesQue); 

WinTerminate (HAncBlk); 
exit (ErrorCode); 

} /* end Quit */ 
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he version of the example program presented in this 
chapter allows you to view any portion of the file that is 
specified on the command line. Horizontal and vertical 
scroll bars are added to the standard window, allowing 
you to scroll through the file in any direction using either the mouse or 
the keyboard. Although this version does not yet permit you to modify 
or add file data, it serves as a convenient utility for viewing a text file 
within a Presentation Manager window, and you might want to keep a 
copy of the program for this purpose. 

In this chapter you will learn how to create horizontal and vertical 
scroll bars and how to maintain the scroll bar sliders in their correct 
relative positions; you will learn how to scroll the contents of the screen 
in response to messages from the scroll bars; and you will learn how to 
invoke the window-drawing routine whenever needed. You will also 
discover how to increase efficiency by redrawing only the portion of the 
window that requires updating (the invalid region). Finally, the chapter 
offers several suggestions for enhancing the program. 

Note that the buffer-management module is unaltered from the pre¬ 
vious version; the current version, however, is able to display any por¬ 
tion of the data within the buffer and not just the first page. The complete 
program listing is given in Figure 4.25, at the end of the chapter. 



• CREATING THE SCROLL BARS 

You can add horizontal and vertical scroll bars to the collection of 
windows created by WinCreateStdWindow by including the 
FCF_HORZSCROLL and FCF_VERTSCROLL styles in the value as¬ 
signed to the control window variable (CtlData in the example pro¬ 
gram; the address of this variable is passed as the third parameter). 
WinCreateStdWindow is described in Figure 2.5, and the styles you 
can select are listed in Tables 2.2, 2.3, and 2.4.) Figure 4.1 illustrates the 
standard window created by the version of the example program 
presented in this chapter, and shows the appearance and position of the 
two scroll bars. 

Figure 4.2 illustrates the components of horizontal and vertical scroll 
bars, and the actions these components initiate. (The figure also gives 
the codes, such as SB_LINEUP, that the system uses to indicate specific 
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actions; these codes are explained later in the chapter.) By clicking the 
mouse pointer on various parts of the horizontal scroll bar, you can 
scroll the window right or left either by a single column or by a "page" 
(in this program, a page is six columns). You can also move the screen to 
any horizontal position in the file by clicking and dragging the slider 
(that is, clicking the mouse with the pointer on the slider and moving 
the pointer with the button held down). Scrolling horizontally enables 
you to view various portions of lines that are longer than the current 
width of the window. The position of the slider indicates the relative 
horizontal position of the window with respect to the file. 

You can use the vertical scroll bar in a similar fashion to scroll up and 
down by one line or one page (a page is an entire screen of data), and to 
move up or down to any relative position in the file. As you will see, the 
program also allows you to scroll through the file using the arrow keys 
and the PgUp and PgDn keys. 

Note that in this book, the term scrolling up means that the view 
within the window moves toward the beginning of the file (even 
though the lines actually move down), and scrolling down means that 
the view moves toward the end of the file. Also, scrolling right means 
moving the view in the window toward the right ends of the lines, and 
scrolling left means moving the view toward the beginnings of the lines. 



® Figure 4.1: 

The standard window created by the current version of the example program 
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After the function main calls WinCreateStdWindow, but before it 
enters the message processing loop, it calls WinSetFocus (Figure 4.3) to 
assign the current focus to the client window, as follows: 

WinSetFocus (HWND__DESKTOP, HClient) ; 

The window with the focus is the one that receives keyboard input 
through messages (note that at a given time, there may be no focus win¬ 
dows). The focus must be assigned to the client window so that the 
client window procedure will receive any messages generated by the 


WinSetFocus 

Purpose: 

Assigns the focus to the specified window. 

Prototype: 

BOOL APIENTRY WinSetFocus 
(hwnd hwndDesktop, Handle of the desktop window, 
HWND_DESKTOP. 

hwnd hwndSetFocus ); Handle of the window to receive the 

focus (which must be a descendant 
window of the desktop window). 

Return Value: 

TRUE if the function was successful; FALSE otherwise. 

Notes: 

You can determine the window that has the current focus by 
calling WinQueryFocus. 

Related Functions: \ 

WinQueryFocus (Figure 5.10) 

• Figure 4.3: 

The WinSetFocus Presentation Manager function 
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arrow or PgUp/PgDn keys. Note that the window with the focus ap¬ 
pears on top of all other windows. 

There are two more common terms related to the concept of the focus 
window. First, the active window is the top-level window (that is, an im¬ 
mediate child of the desktop window) that is placed above all other top- 
level windows. If the active window is a standard window, its title bar 
and sizing border appear highlighted; if it is a dialog box (see Chapter 
8), its entire border is highlighted to indicate the active status. The focus 
window (if one currently exists) is always either the active window or a 
descendant of the active window. The active and focus windows are set 
either by a program action (such as calling WinSetFocus), or by a user 
action (through the keyboard or mouse). Second, the program that cur¬ 
rently owns the active window is known as the active application. 

Other than specifying the two scroll bar styles in the call to Win- 
CreateStdWindow, and calling WinSetFocus to assign the focus to the 
client window, the function main is the same as it was in the previous 
version of the example program. To initialize and maintain scroll bars, 
however, the window procedure of the current version must provide 
some additional code in the routines that process the WM_CREATE 
and WM_SIZE messages (these messages were described in Chapter 3). 


The WM_CREATE Message 

As mentioned in Chapter 3, the WM_CREATE message (Figure 
3.16) is sent to the client window immediately after the window has 
been created, but before it becomes visible. The new version of the Cre¬ 
ate function, which processes this message, is listed in Figure 4.4. In ad¬ 
dition to the tasks performed by the previous version. Create obtains 
the character width for the Courier font from the lAveCharWidth field 
of the FONTMETRICS structure (see Figure 3.21). This value is stored in 
the variable xChar and will be used by the routines that process the 
WM_SIZE and WM_PAINT messages, described later in the chapter. 
Note that although this field is labeled as the average character width, 
the characters belonging to the Courier font are uniformly spaced, and 
therefore the field actually supplies the exact, constant character width. 

The Create function also obtains the handles for the horizontal and 
vertical scroll bars, which are required by several of the routines that 



MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

HPS HPresSpace ; /* Presentation space handle. 

FONTMETRICS Metrics; /* Structure to hold font dimensions. 

LONG NumberStructs =1; /* Number of structures from GpiQueryFonts. 

GpiLoadFonts /* Load Courier font. 

(HAncBlk, /* Anchor block handle. 

"\\0S2 \\DLL\\COURIER.FON"); /* Full path name of font file. 

HPresSpace = WinGetPS (hwnd); 


GpiQueryFonts /* Obtain information on Courier font. 

(HPresSpace, /* Handle to presentation space. 

QF_PRIVATE, /* Enumerate private fonts. 

"Courier", /* Font face name. 

&NumberStructs, /* Number of FONTMETRICS structures returned, 

(long)sizeof (FONTMETRICS),/* Length of structure for EACH font. 
&Metrics); /* Address of FONTMETRICS structure(s). 


xChar = (SHORT)Metrics.lAveCharWidth; 

yCharTot = (SHORT)Metrics.IMaxBaselineExt; 
yCharDesc = (SHORT)Metrics.IMaxDescender; 


FontAttributes. 
FontAttributes. 
FontAttributes. 
strcpy (FontAtt 
FontAttributes. 
FontAttributes. 
FontAttributes. 
FontAttributes. 
FontAttributes. 
FontAttributes. 


usRecordLength = sizeof (FontAttributes)? 
fsSelection = Metrics.fsSelection; 
lMatch = Metrics.IMatch; 
ributes.szFacename,Metrics.szFacename); 
idRegistry = Metrics.idRegistry; 
usCodePage = Metrics.usCodePage; 
IMaxBaselineExt = Metrics.IMaxBaselineExt; 
lAveCharWidth = Metrics.lAveCharWidth; 
fsType = FATTR_TYPE_FIXED; 
fsFontUse = 0; 


WinReleasePS (HPresSpace); 

/*** Get handles to horizontal and vertical scroll bar windows. **************/ 
HHScroll = WinWindowFromID 

(WinQueryWindow (hwnd, QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 

FID_H0RZSCROLL); /* Identifier for vertical scroll bar. */ 

HVScroll = WinWindowFromID 

(WinQueryWindow (hwnd, QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 


FID_VERTSCROLL); 


/* Identifier for vertical scroll bar. */ 


return FALSE; 


} /* end Create */ 


• Figure 4 A: 
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process subsequent messages. Create first obtains the horizontal win¬ 
dow handle by calling the Presentation Manager function WinWin- 
dowFromlD (Figure 4.5), which returns the handle of a child window. 
The program passes the handle of the frame window (which is the 
parent of both scroll bar windows) and the identifier of the horizontal 
scroll bar (FIDJHORZSCROLL); WinWindowFromlB returns the hand¬ 
le of the horizontal scroll bar. 

To obtain the handle of the frame window. Create must call another 
Presentation Manager function, WinQueryWindow (Figure 4.6), which 
returns the handle of the window having the selected relationship to a 
specified window. Create passes the values hwnd and QW_PARENT to 
request the handle of the parent of the current window; the parent of 
the current window is the frame window. Create must call WinQuery¬ 
Window rather than simply passing the global variable HFrame, be¬ 
cause at this point in the program, WinCreateStdWindow has not yet 
returned and therefore HFrame does not contain a valid handle. 


WinWindowFromID 

Purpose: 

Returns the handle belonging to a child window. 

Prototype: 

HWND APIENTRY WinWindowFromID 
(hwnd hwndParent , Handle of the parent of the window. 

ushort id) ; Identifier of the child window. 

Return Value: 

If successful, returns the handle of the window that is the 
child of the window specified by the first parameter, and 
that has the ID given by the second parameter. If an error oc¬ 
curs, the value NULL is returned. 


• Figure 4.5: 

The WinWindowFromID Presentation Manager function 
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WinQueryWindow 


Purpose: 


Returns the handle of the window 
relationship to a specified window. 

that has the selected 

: Prototype: 


HWND APIENTRY WinQueryWindow 


j (hwnd hwnd, Handle of the window to query. 

short cmd, Specifies the relationship of the window 

whose handle is to be returned to the 

window specified by hwnd; you can select 
one of the following values: 

Value 

Meaning 

QW_NEXT 

Next window below 

QW_PREV 

Next window above 

QW_TOP 

Top-most child 
window 

QW_BOTTOM 

Bottom-most child 
window 

QW_NEXTTOP 

Next top-level 
window that would 


be activated by the 

Alt-Esc key of the 
user interface 

QW_PREVTOP 

Previous top-level 
window in the 


sequence of windows 
activated by the 

Alt-Esc key 

QW_OWNER 

Owner of the window 

QW_PARENT 

Parent of the window 


• Figure 4.6: 
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bool fLock) ; If this parameter is TRUE, the window 

will be locked; if it is FALSE, the 
window will not be locked. 

Return Value: 

The handle of the window related to hwnd, or NULL if an 
error occurred. 


® Figure 4.6: 

The WinQueryWindow Presentation Manager function (continued) 

Note that a window identifier is distinct from a window handle. A win¬ 
dow handle is a number returned by the system when it creates a 
window; the value of the handle can differ each time a specific win¬ 
dow, such as a scroll bar, is created. A window identifier, however, can 
be specified when you create the window (for example, through the 
WinCreateWindow function or through a dialog template, discussed in 
Chapter 8). When the system creates control windows through the Win- 
CreateStdWindow function, it assigns each of these windows a 
predefined standard identifier. For example, the horizontal scroll bar is 
given the identifier FID_HORZSCROLL and the vertical scroll bar is as¬ 
signed FID_VERTSCROLL. Unlike window handles, the identifier for a 
specific control window created through WinCreateStdWindow is al¬ 
ways the same. The identifiers for the control windows are listed in 
Table 4.1. 

In a similar manner, Create next obtains the handle for the vertical 
scroll bar. The horizontal scroll bar handle is saved in the variable 
HHScroll, and the vertical scroll bar handle is saved in HVScroll. 


The WM_SIZE Message 

WM_SIZE is the next message processed by the client window 
procedure during window creation, and subsequently each time the 
window changes size. The new version of the routine that processes this 
message. Size, is listed in Figure 4.7. This routine first obtains the cur¬ 
rent vertical dimension (yWin) and horizontal dimension (xWin) of the 
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• Table 4.1: Identifiers for the Standard Control Windozvs 


Identifier 

Control Window 

FIDHORZSCROLL 

Horizontal scroll bar 

FIDMENU 

Application menu 

FID_MINMAX 

Minimize/maximize box 

FIDSIZEBORDER 

Sizing border 

FID_SYSMENU 

System menu 

FID_TITLEBAR 

Title bar 

FIDJVERTSCROLL 

Vertical scroll bar 


client window; both of these values will be used by this function and by 
the routines that process subsequent messages, such as WM_PAINT. 

Next, the function Size calculates the value of TopLineMax, which 
contains the largest line number that will be placed at the top of the 
window as the window data are scrolled. The expression used to calcu¬ 
late this value, 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

assures that the window is not scrolled down farther than necessary to 
show the last line in the file (remember that file lines are numbered 
beginning with 0). Note that as the window becomes smaller vertically, 
TopLineMax becomes larger (except in the case where the file data does 
not completely fill the window; in this case TopLineMax remains 0). 
Therefore, TopLineMax must be recalculated each time the window 
changes size; accordingly, the expression is placed in the function Size 
rather than in Create. 

Once TopLineMax has been calculated, the program reassigns the 
variable TopLine, which is the number of the file line currently dis¬ 
played at the top of the window, to make sure that it does not exceed the 
maximum value contained in TopLineMax. (TopLine is initialized to 0.) 
Note that the WM_PAINT message is sent shortly after the WM_SIZE 
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message; the routine that processes WM_PAINT will use the updated 
value of TopLine to paint the appropriate lines within the window. 

At this point, the function Size sets the range and position of the 
slider within the vertical scroll bar (see Figure 4.2). Note that your pro¬ 
gram is responsible for maintaining the slider; the scroll bar does not 
perform this action automatically (as you will see, the only automatic 


MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

/*** obtain vertical and horizontal dimensions of client window. ************/ 

yWin = SHORT2 FROMMP (mp2) ? 
xWin = S HORT1FROMMP (mp2) ; 

/*** Update 'TopLine' and adjust vertical scroll bar position. **************/ 

TopLineMax = max (0,LastLine - yWin / yCharTot +1); 

TopLine = min (TopLine,TopLineMax); 


WinSendMsg /* Adjust vertical scroll bar position. */ 

(HVScroll, /* Recipient handle: vertical scroll bar .*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFROM2SHORT (TopLine, 0) , /* Position. V 

MPFROM2SHORT (0, TopLineMax)); /* Range. V 

/*** Enable scroll bar only if needed (TopLineMax > 0). ****************/ 

WinEnableWindow 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

TopLineMax ? 1 : 0); /* Enable only if max. != 0. */ 

/*** Update 'FirstCol' and adjust horizontal scroll bar position. ************/ 


FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 

FirstCol = min (FirstCol, FirstColMax); 

WinSendMsg /* Adjust horizontal scroll bar position. */ 

(HHScroll, /* Recipient handle: horizontal scroll bar*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFROM2SHORT (FirstCol, 0), /* Position. */ 

MPFROM2SHORT (0, FirstColMax)); /* Range. */ 

return FALSE; 

} /* end Size */ 


• Figure 47: 

The function Size from the example-program 
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action taken by a scroll bar is to send messages to report input from the 
user). You must set the following two values for the slider: 

• The slider range, which is specified as a minimum value (the 
value represented when the slider is at the top of the scroll bar) 
and a maximum value (the value represented when the slider is 
at the bottom of the scroll bar). In the example program, the posi¬ 
tion of the slider is used to indicate the number of the line that ap¬ 
pears at the top of the window . Therefore, this program always sets 
the minimum range value to 0, and the maximum range value to 
TopLineMax. 

• The current slider position within the specified range. In the ex¬ 
ample program, this is simply Topline. 

Once TopLineMax and TopLine have been calculated, the program 
must set the slider position and range based upon the new values of 
these variables. The two slider parameters are set by sending a message 
directly to the vertical scroll bar window. 

In addition to receiving messages, a window procedure can send mes¬ 
sages to other windows (as you will see later, it can even send messages to 
itself). Sending messages to window procedures provided by the 
Presentation Manager is an important general method for obtaining ser¬ 
vices from the system. The collection of predefined messages you can 
send to system window procedures is thus a significant extension of the 
basic Presentation Manager API. 

When you send a message to a scroll bar window, the system invokes 
the window procedure associated with this window (which by default 
is a procedure provided by the system), passing it the parameters you 
have supplied. The example program sends the message by calling the 
Presentation Manager function WinSendMsg (Figure 4.8). The first 
parameter to this function is the handle of the target window 
(HVScroll, the vertical scroll bar window). The second parameter is the 
identifier of the actual message, SBM_SETSCROLLBAR (Figure 4.9), 
which causes the vertical scroll bar procedure to set both the range and 
the position of the scroll bar. The next two parameters specify the mes¬ 
sage parameters to be passed to the target window procedure 
(equivalent to the mpl and mp2 parameters processed by the client 
window procedure). The first message parameter gives the current 
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slider position (the low-order word is set to the position and the high- 
order word is 0), and the second gives the slider range (the low-order 
word contains the minimum range value and the high-order word the 
maximum value). These parameters are constructed using the OS/2 
macro MPFROM2SHORT, described in Table 3.2. 

Note that WinSendMsg causes the system to send a message by 
directly calling the window procedure belonging to the target window; 
the message is not placed in the message queue. In contrast, the Presen¬ 
tation Manager function WinPostMsg sends a message by placing it in 
the message queue of the target window. 

The function Size next makes sure that the vertical scroll bar window 
is enabled only if the file contains sufficient data to warrant vertical 
scrolling. If the scroll bar window is disabled, it still appears on the 
screen; however, if the user clicks the mouse on this window, the win¬ 
dow procedure merely beeps and does not send messages to the client 
window. The program sets the enabled status of this window by calling 
the Presentation Manager function WinEnableWindow (Figure 4.10). 
The first parameter to this function is the handle of the specific window; 
if the second parameter is TRUE, the window is enabled, and if it is 
FALSE, the window is disabled. The program passes the handle of the 
vertical scroll bar window, and enables this window only if TopLine- 
Max is greater than 0 (otherwise, no scrolling is possible). 

The program next calculates the value of the program variable First- 
ColMax based upon the current window dimensions. This variable 
contains the number of the greatest file column that can be displayed at 
the far left of the window (the file column number is the offset of a char¬ 
acter within a line in the file buffer). The expression used to calculate 
this value, 

FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 

assures that the window does not scroll farther to the right than is neces¬ 
sary to display the longest possible line in the file (LINEBUFSIZ - 2). The 
program then updates the value of FirstCol, which contains the num¬ 
ber of the file column currently displayed at the far left of the window, 
to make sure that this variable does not exceed the maximum value 
contained in FirstColMax. 

Finally, the program sends a message to set the range and position of 
the horizontal scroll bar slider in the same manner that it set the vertical 
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WinSendMsg 

Purpose: 

Sends a message to the specified window. 
Prototype: 

MRESULT APIENTRY WinSendMsg 


(HWND hwnd, 
USHORT msg, 

MPARAM mpl, 

MPARAM mp2) , 

Return Value: 


Handle of the target window. 

The identifier of the message that is being 
sent. 

The first message parameter; the meaning is 
specific to the message. 

The second message parameter; the meaning 
is specific to the message. 


The value that is returned by the window procedure of the 
target window. 

Notes: 

This function causes the system to directly invoke the win¬ 
dow procedure belonging to the target window; the message 
is not placed in the window's message queue (you can place 
a message in the target window's queue by calling WinPost- 
Msg). WinSendMsg does not return until the message has 
been processed (unlike WinPostMsg, which returns imme¬ 
diately after the message is placed in the queue). 

Related Functions: 

WinPostMsg (Figure 12.11) 


© Figure 4.8: 

The WinSendMsg Presentation Manager function 
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SBM_SETSCROLLBAR 

Purpose: 


This message is sent to a horizontal or vertical scroll bar win¬ 
dow to cause it to set the range and position of the scroll bar 

slider. 


Parameters: 


MPARAM mpl 


low-order word: 

Slider position. 

high-order word: 

0 

MPARAM mp2 


low-order word: 

Low value of range. 

high-order word: 

High value of range. 

Return Value: 


TRUE if the operation was successful, or FALSE if an error 

occurred. 


Notes: 


The system procedure for the scroll bar window immedi¬ 
ately redraws the scroll bar to reflect the requested values. 

See also SBMJ3ETPOS (Figure 4.17), which sets only the 

slider position. 



® Figure 4.9: 


The SBM__SETSCROLLBAR Presentation Manager message 
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scroll bar slider. Note, however, that the WinEnableWindow function is 
not called. Since the maximum visible line length (LINEBUFSIZ - 2) 
is much larger than the maximum window width, horizontal scroll¬ 
ing is always permitted. (Note that the scroll bar windows are enabled 
by default when they are created.) 


WinEnableWindow 

Purpose: 

Enables or disables the specified window. 

Prototype: 

BOOL APIENTRY WinEnableWindow 
(hwnd hwnd, The window handle. 

bool fEnable) ; If this parameter is TRUE the window is 
enabled; if it is FALSE, the window is 
disabled. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

If the enabled state of the target window is changed through 
this function call, this window is sent a WM_ENABLE mes¬ 
sage. The changes in the window's appearance and function 
between the enabled and disabled state depend upon the 
specific window. 


• Figure 4.10: 

The WinEnableWindow Presentation Manager message 
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PROCESSING 

• THE SCROLL BAR MESSAGES 

As mentioned earlier in the chapter, the only action initiated by 
the scroll bar windows is to send messages to the client window to 
report input from the user. To generate the actual scrolling of data and 
to update the scroll bar slider positions, the client window procedure 
must receive and process these messages. The horizontal scroll bar 
sends the general message WM_HSCROLL, and the vertical scroll 
bar sends the general message WM VSCROLL. Each of these messages 
is accompanied by a code indicating the exact scrolling activity that has 
taken place. (Actually, the scroll bar windows send these messages to 
their owner, the frame window; the frame window then passes the mes¬ 
sages to the client window.) 

Accordingly, the main switch statement of the client window proce¬ 
dure (WndProc) must contain branches for processing these two new 
messages. The current version of WndProc is listed in Figure 4.11. Note 
that this function also contains a branch for the WMJZHAR message, 
which will be explained in the next main section, Rerouting Keyboard 
Input. 


The WM_HSCROLL Message 

The horizontal scroll bar sends the WMJHSCROLL message (Fig¬ 
ure 4.12) to the client window (through the frame window) whenever it 
receives relevant input from the user. This input can originate either 
from the mouse or from the keyboard (the manner in which scroll bars 
receive keyboard input is explained in the section on Rerouting Key¬ 
board Input). The WM_HSCROLL message is accompanied by a code 
in the high-order word of mp2, which indicates the specific type of 
horizontal scroll bar activity The meanings of these activity codes are 
listed in Table 4.2. Note that holding down a keyboard key or mouse 
button will cause the appropriate message to be repeated. See also Fig¬ 
ure 4.2, which illustrates the components of the scroll bars associated 
with each of the codes used in the example program. 

The WMJHSCROLL message is processed by the function HScroli of 
the example program, which is listed in Figure 4.13. This function first 






MRESULT EXPENTRY WndProc 

(HWND hwnd, /* Window handle. */ 

USHORT msg, /* The message. */ 

MPARAM mpl, /* Message-specific information. */ 

I MPARAM mp2) /* Message-specific information. */ 

{ 

switch (msg) 

{ 

case WM_CHAR: /* Message sent when keyboard key is received. */ 

return Character (hwnd, msg, mpl, mp2); 

case WM_CREATE: /* Message sent when window is first created. */ 

return Create (hwnd, msg, mpl, mp2); 

case WM_HSCROLL: /* Message sent on horizontal scroll activity. */ 

return HScroll (hwnd, msg, mpl, mp2); 

case WM_PAINT: /* Message sent when window data is invalid. */ 

return Paint (hwnd, msg, mpl, mp2); 

case WM_SIZE: /* Message sent whenever window changes size. */ 

return Size (hwnd, msg, mpl, mp2); 

case WM_VSCROLL: /* Message sent on vertical scroll activity. */ 

return VScroll (hwnd, msg, mpl, mp2); 

default: /* Perform default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} /* end switch */ 

} /* end WndProc */ 

® Figure 4.11: 

The WndProc function of the example program 

determines the number of columns that the window should be scrolled 
according to the activity code passed with the message, and assigns this 
number to the variable Delta. A negative value in Delta indicates scroll¬ 
ing left, and a positive value scrolling right. The program arbitrarily 
scrolls by six columns in response to a page left (SB_PAGELEFT) or page 
right (SBJPAGERIGHT) message. 

Note that there are two methods for processing movement of the 
slider. First, as the user drags the slider, the scroll bar sends a rapid 
series of messages with the SBSLIDERTRACK ac tivity code (in the 
high-order word of mp2) and the current slider position (in the low- 
order word of mp2). If the program can process these messages as fast 
as they are sent, it can update the screen and the slider position with 
each message. As a result, the screen scrolls while the user drags the 
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WM_HSCROLL 


Purpose: 


Sent by a horizontal scroll bar window to its owner to report 
relevant scroll bar events. 

Parameters: 


MPARAM mpl 

The scroll bar window identifier. 

MPARAM mp2 

low-order word: 

Contains the position of the slider if 
the high-order word equals 
SB_SLIDERPOSITION or 

SB SLIDERTRACK; otherwise, it is set 
to FALSE. 

high-order word: 

A code for the specific event; these 
codes are described in Table 4.2. 

Return Value: 


FALSE. 



® Figure 4.12: 

The WM_HSCROLL Presentation Manager message 


slider. If the update routine is lengthy or the machine slow, however, 
the program may not be able to process the messages as quickly as they 
are received, and the scrolling action becomes rough. 

Second, when the user releases the mouse button after dragging the 
slider to a new position, the system sends a single SB_SLIDER- 
POSITION message specifying the final new position. If the program 
ignores the SBSLIDERTRACK messages, and processes only the 
SB_SLIDERPOSITION message, the window data does not scroll as 
the slider is moved, but rather jumps to its final position when the 
mouse button is released. On a slower machine, the visual effect of this 
method is superior to the first method, and it is the approach used by 
the example program. Note also that since the SB_SLIDERPOSITION 
message provides an absolute slider position, the program subtracts the 
current position (FirstCol) from the position supplied with this mes¬ 
sage to obtain the number of columns to scroll the window (Delta). 
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• Table 4.2: Activity Codes for the WM_HSCROLL Message 


Code 

Origin 

Required Action 

SB_LINELEFT 

Clicking on left 
scroll bar arrow 
or hitting <— key 
on keyboard 

Scroll one column 
left 

SB_LINERIGHT 

Clicking on right 
scroll bar arrow 
or hitting —» key 
on keyboard 

Scroll one column 
right 

SB_PAGELEFT 

Clicking on area 
left of slider 

Scroll one page 
left 

SBPAGERIGHT 

Clicking on area 
right of slider 

Scroll one page 
right 

SBSLIDERPOSITION 

Dragging the 
slider to a new 
position and 
releasing the 
mouse button 

Scroll screen and 
update the slider 
to the new posi¬ 
tion, encoded in 
the low-order 
word of mp2 

SBJ3LIDERTRACK 

Dragging the 
slider causes a 
series of these 
messages 

If this command 
is used, update 
the screen and 
slider position 
with each 
message 

SBENDSCROLL 

Releasing the 
mouse button 
(and the pointer is 
not on the slider) 

Can be ignored j 




MRESULT EXPENTRY HScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

SHORT Delta; /* Amount to scroll. */ 

/*** Determine amount to scroll. *********************************************/ 

switch (SH0RT2FR0MMP (mp2)) /* Switch on code from scroll bar. */ 

case SB_LINELEFT: 

Delta = -1; 
break; 

case SB_LINERIGHT; 

Delta = 1; 
break; 

case SB_PAGELEFT: 

Delta = -6; 
break; 

case SB_PAGERIGHT: 

Delta = 6; 
break; 

case SB_SLIDERPOSITION: 

Delta = SHORT1FROMMP (mp2) - FirstCol; 
break; 
default: 

Delta = 0; 
break; 

} 

Delta = max (-FirstCol, min (Delta,FirstColMax - FirstCol)); 

/*** Scroll the window if necessary. *****************************************/ 

if (Delta) 

{ 

/*** Adjust first column value. ************************************/ 
FirstCol += Delta; 

/*** Scroll the window data. ***************************************/ 


WinScrollWindow 

(hwnd, /* Handle of client window. */ 

-Delta * xChar, /* Horizontal scroll amount. */ 

0, /* Vertical scroll amount. */ 

0, /* Must be 0. */ 

0 , /* Must be 0. */ 

0, /* Must be 0. */ 

0, /* Must be 0. */ 

SW_INVALIDATERGN); /* Invalidate "exposed" region. */ 

/*** Force repainting of invalid window region. ********************/ 
WinUpdateWindow 

(hwnd); /* Handle of client window. */ 

/*** Update the position of the horizontal scroll bar slider. ******/ 
WinSendMsg 

(HHScroll, /* Handle to horizontal scroll bar. */ 

SBM_SETPOS, /* Set position of slider. */ 

MPFR0M2SH0RT (FirstCol,0), /* Current position. */ 

°) '* /* Second parameter n/a. */ 


return FALSE; 

} /* end HScroll */ 

• Figure 4,13: 

The function HScroll of the example program 
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Once the program has determined the initial value for Delta, it ad¬ 
justs this value to make sure that when Delta is combined with First- 
Col, the result is within the valid range from 0 to FirstColMax. This 
adjustment is accomplished through the following expression: 

Delta = max (-FirstCol, min (Delta,FirstColMax - 

FirstCol)); 

Next, provided that Delta is not 0, the program updates the value of 
FirstCol, scrolls the window data, forces repainting of the resulting in¬ 
valid region of the window, and adjusts the horizontal scroll bar posi¬ 
tion. The value of FirstCol is adjusted by the number of columns stored 
in Delta. As you will discover, the subsequent actions of this routine 
will cause the system to invoke the window-painting function Paint 
(through the WM_PAINT message); Paint will use the value in FirstCol 
to display the correct portions of the file lines (that is, it will display the 
lines beginning with the character having the offset given by FirstCol). 

The program scrolls the data within the window by calling the 
Presentation Manager function WinScrollWindow (Figure 4.14). This 
function scrolls the data in the specified window (hwnd, the client win¬ 
dow) horizontally by the amount specified in the second parameter 
(dx), which is assigned the following value: 

-Delta * xChar 

The - sign is required, because a positive Delta means to scroll the win¬ 
dow to the right and therefore move the data to the left; to move the data 
left, however, you must pass WinScrollWindow a negative dx value. 
Therefore, Delta and dx must have opposite signs. Note from Figure 
4.14 that the scrolling distance is specified in device units', for the presen¬ 
tation space used by the example program, these units are screen pixels 
(conveniently, the same units used for the total window size and for the 
character dimensions). 

The last parameter to WinScrollWindow (rgfsw), specifies the scroll¬ 
ing options. The example program passes the value SW_IN- 
VALIDATERGN, which causes the function to invalidate the region of 
the window that is left behind when the existing data are moved. 
Remember from Chapter 2 that an invalid region of a window is an area 
that must be repainted, and when a section of a window becomes 
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WinScrollWindow 

Purpose: 

Scrolls the contents of a window a specified horizontal and 

vertical distance. 

Prototype: 

SHORT APIENTRY WinScrollWindow 

(HWND hwnd, 

Handle of window to scroll. 

SHORT dx, 

The amount (in device units) to move 
the window data to the right with 
respect to the window (a negative 
value moves the data left). 

SHORT dy, 

The amount (in device units) to move 
the window data up with respect to 
the window (a negative value moves 
the data down). 

PRECTL prclScroll, 

Points to a RECTL structure (Figure 

2.22) containing the dimensions of the 
rectangular section of the window to 
be scrolled; a value of NULL causes 
the entire window to be scrolled. 

PRECTL preclClip, 

Points to a RECTL structure containing 
the dimensions of the clip rectangle. 

HRGN hrgnUpdate, 

If not NULL, hrgnUpdate is assigned 
the region uncovered by the scroll. 

PRECTL prclUpdate, 

Points to a RECTL structure that will 
be assigned the dimensions of the 
rectangle invalidated as a result of 
scrolling. 


• Figure 4.14: 

The WinScrollWindow Presentation Manager function 



USHORT rgfsw); 


The scroll options; you may specify 
one or more of the following values 
(combined with the I operator), or 
pass 0 for no options: 

Option Meaning 

SW_SCROLLCHILDREN Scroll all child 

windows 

SWJNVALIDATERGN Invalidate the 

region(s) of the 
screen that 
remain after the 
data is scrolled 

Return Value: 

One of the following codes, indicating the shape of the in¬ 
valid region remaining after scrolling the window. 

Return Value Meaning 

RGNERROR An error occurred 

RGM_NULL NO region (a NULL rectangle) 

RGN_RECT Simple rectangular invalid region 

RGN_COMPLEX Complex invalid region 

Notes: 

If the window data is scrolled both vertically and horizontal¬ 
ly, a complex invalid region can result (not a simple rec¬ 
tangle). The dimensions of the update rectangle returned by 
the WinBeginPaint function, however, are for the smallest 
simple rectangle that bounds the entire invalid region. 

Related Functions: 

WinBeginPaint (Figure 2.20) 

Figure 4.14: 

The WinScrollWindow Presentation Manager function (continued) 
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invalid, the system sends a WM_PAINT message to the window proce¬ 
dure. Therefore, a single call to the WinScrollWindow function not 
only moves the existing data within the window, but also automatically 
causes the Paint function to fill in all characters from the newly "ex¬ 
posed" columns of the file. Figure 4.15 illustrates the invalid region 
created by scrolling the screen horizontally. 

Note, however, that the creation of an invalid region normally causes 
the system to post a WM PAINT message to the client window mes¬ 
sage queue; the client window will receive this message only after it has 
processed all other prior messages waiting in its queue. The problem 
with this rather leisurely process is that if the user holds down the 
mouse button or keyboard key, the window procedure may receive and 
process an entire series of WM_HSCROLL or WM_VSCROLL messages 
before it receives the corresponding WM_PAINT messages. The result 
is that the window scrolls without updating the invalid region until the 
user releases the button or key. 

To solve this problem, the example program calls the WinUpdate- 
Window Presentation Manager function (Figure 4.16) immediately 
after scrolling the window data. WinUp date Window causes the system 
to call the window procedure associated with the specified window 
(hwnd, the client window) directly, passing it a WM_PAINT message, 
rather than inserting this message into the queue. As a result, the in¬ 
valid region of the window is updated immediately (in fact, Win- 
Up date Window does not return until the WM_PAINT message has 
been processed). You might try temporarily removing the WinUpdate- 
Window call from the example program to observe the effect of not up¬ 
dating the window immediately. 

Calling functions that invalidate a section of the client window is the 
primary method for a program to modify the data that it displays on the 
screen. The ability to invalidate a window region allows a program to 
use a single routine for updating the window display in response to the 
external demands of the system or the internal activities of the program 
itself. 

Note that you can also explicitly invalidate any region of a win¬ 
dow by calling the WinlnvalidateRect Presentation Manager function 
(described in Figure 5.8). Accordingly, one method for scrolling the 
window horizontally would be to simply adjust the variable FirstCol 
and call WinlnvalidateRect to invalidate the entire client window. The 
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• Figure 415: 

The invalid area created by scrolling a window horizontally 
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WinUpdateWindow 

Purpose: 

Causes the system to send a WM_PAINT message to the 
specified window by directly calling the window procedure. 

Prototype: 

BOOL APIENTRY WinUpdateWindow 
(hwnd hwnd); The handle of the window to be updated. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

The window procedure of the specified window is called 
directly with the WMJPAINT message; this message is not 
placed in the window's message queue. If the target window 
belongs to the current thread, this function does not return 
until the WM_PAINT message has been processed. 


© Figure 4.16: 

The WinUpdateWindow Presentation Manager function 

function Paint would then automatically repaint the entire window, 
starting at the appropriate character offset within the file lines. Thus, 
scrolling could be effected without calling WinScrollWindow. The 
problem with this simple approach, however, is that it is noticeably 
slower than allowing the system to scroll the window data and then 
having the Paint function repaint only the invalid region. 

Finally, the HScroll function sends the SBM_SETPOS message (Fig¬ 
ure 4.17) to the horizontal scroll bar to update the position of the slider 
to reflect the new file location. Unlike the SBM_SETSCROLLBAR mes¬ 
sage described earlier in the chapter, the SBM_SETPOS message up¬ 
dates only the slider position and not the range (it is not necessary to 
update the range unless the window changes size). 
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SBIVLSETPOS 

Purpose: 

This message is sent to a horizontal or vertical scroll bar win¬ 
dow to cause it to set the position of the scroll bar slider. 

Parameters: 

MPARAM mpl 

low-order word: New position of slider. j 

high-order word: 0. 

MPARAM mp2 0. ; 

Return Value: 

TRUE if the operation was successful, or FALSE if an error 
occurred. 

Notes: 

The system procedure for the scroll bar window immedi¬ 
ately redraws the scroll bar to reflect the requested values. 
See also the message SBM_SETSCROLLBAR (Figure 4.9), 
which sets both the slider position and the slider range. 


• Figure 4.17: 

The SBM_SETPOS Presentation Manager message 

The WM_VSCROLL Message 

The vertical scroll bar reports scrolling activities by sending the 
client window the WM_VSCROLL message, which is exactly analogous 
to the WM_HSCROLL message, and is described in Figure 4.18. The 
specific activity codes included with this message are defined in Table 
4.3, and Figure 4.2 illustrates the components of a horizontal scroll bar 
that are associated with each of the codes used in the example program. 

The WM_VSCROLL message is processed by the VScroll function of 
the example program, which is listed in Figure 4.19. The basic logic 
of this function is identical to that of the HScroll function. VScroll first 
uses the activity code to set the value of Delta, which is the number of 
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WM_VSCROLL 


Purpose: 


Sent by a vertical scroll bar window to its owner to report 
relevant scroll bar events. 

Parameters: 


MPARAM mpl 

MPARAM mp2 

The scroll bar window identifier. 

low-order word: 

Contains the position of the slider if 
the high-order word equals 

SB SLIDERPOSITION or 


SB SLIDERTRACK; otherwise, it is set 


to FALSE. 

high-order word: 

A code for the specific event; these 
codes are described in Table 4.3. 

Return Value: 


FALSE. 



• Figure 4.18: 

The WM_VSCROLL Presentation Manager message 


rows the window should be scrolled vertically (a positive value indi¬ 
cates scrolling down). Note that a page-up (SBJPAGEUP) or page- 
down (SBJPAGEDOWN) activity code sets Delta to the full number of 
complete lines contained in the window (negative or positive), which is 
calculated using the following expression: 

yWin / yCharTot 

Delta is subsequently adjusted so that when it is combined with Top- 
Line (the number of the line currently displayed at the top of the win¬ 
dow), the result is within the valid range from 0 to TopLineMax. The 
following expression adjusts the value of Delta: 

Delta = max (-TopLine, min (Delta, TopLineMax - 

TopLine)); 




® Table 43: The Activity Codes for the WM_VSCROLL Message 


SB LINEUP 


SB_LINEDOWN 


SB PAGEUP 


SB PAGEDOWN 


Origin 

Clicking on scroll 
bar up-arrow or 
hitting T key on 
keyboard 

Clicking on scroll 
bar down-arrow 
or hitting i key 
on keyboard 

Clicking on area 
above slider 

Clicking on area 
below slider 


SB_SLIDERPOSITION Dragging the 

slider to a new 
position and 
releasing the 
mouse button 


SB SLIDERTRACK 


SB ENDSCROLL 


Dragging the 
slider causes a 
series of these 
messages 


Releasing the 
mouse button 
(and the pointer is 
not on the slider) 


Required Action 
Scroll one row up 


Scroll one row 
down 


Scroll one page up 

Scroll one page 
down 

Scroll screen and 
update the slider 
to the new posi¬ 
tion, encoded in 
the low- order 
word of mp2 

If this command 
is used, update 
the screen and 
slider position 
with each 
message 

Can be ignored 








MRESULT EXPENTRY VScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


SHORT Delta; 


/* Amount to scroll. 


/*** Determine amount to scroll. *********************************************/ 

switch (SH0RT2FROMMP (mp2)) /* Switch on code from scroll bar. */ 

{ 

case SB_LINEUP: 

Delta = -1; 
break ? 

case SB_LINEDOWN: 

Delta = 1; 
break; 

case SB_PAGEUP: 

Delta = -yWin / yCharTot; 
break; 

case SB_PAGEDOWN: 

Delta = yWin / yCharTot; 
break; 

case SB_SLIDERPOSITION: 

Delta = SHORT1FROMMP (mp2) - TopLine; 

break; 
default: 

Delta = 0; 
break; 

} 

Delta = max (-TopLine, min (Delta,TopLineMax - TopLine)); 

/*** Scroll the window if necessary. *****************************************/ 
if (Delta) 

/*** Adjust top line value. ****************************************/ 
TopLine += Delta; 


/*** Scroll the window data. ***************************************/ 
WinScrollWindow 

(hwnd, /* Handle of client window. */ 
0, /* Horizontal scroll amount. */ 
yCharTot * Delta, /* Vertical scroll amount. */ 
0, /* Must be 0. */ 
0, /* Must be 0. */ 
0, /* Must be 0. */ 
0, /* Must be 0. */ 
SW_INVALIDATERGN); /* Invalidate "exposed" region. */ 


/*** Force repainting of invalid window region. ********************/ 
WinUpdateWindow 

(hwnd); /* Handle of client window. */ 

/*** Update the position of the vertical scroll bar slider. ********/ 
WinSendMsg 

(HVScroll, /* Handle to vertical scroll bar. */ 

SBM_SETPOS, /* Set position of slider. */ 


Figure 4.19: 

The function VScroll of the example program 
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MPFROM2SHORT (TopLine,0),/* Current position. 

0) ; /* Second parameter n/a. 

} 

return FALSE; 

} /* end VScroll */ 

• Figure 419: 

The function VScroll of the example program (continued) 


Client Window Before Scrolling 


Client Window After Scrolling 
Down One Line 


Invalid Region 


• Figure 4.20: 

The invalid area created by scrolling a window vertically 
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If the final value of Delta is not equal to 0, the program proceeds to 
update TopLine, to scroll the window data, to force the updating of the 
client window, and finally, to set the horizontal slider to the correct 
position. These steps are the same as those performed by the HScroll 
function, explained in the previous section. Figure 4.20 illustrates the 
vertical scrolling process and the resulting invalid region. 


• REROUTING KEYBOARD INPUT 

All keyboard input (as well as mouse input) is initially received by 
the Presentation Manager itself. The Presentation Manager, however, 
notifies the window that currently has the focus of each key that is 
pressed or released by sending a WM_CHAR message (Figure 6.1) to 
this window. The message parameters that accompany this message 
identify the specific key and provide other information. (The keyboard 
interface is fully described in Chapter 6.) 

When a scroll bar window receives a WM_CHAR message for one of 
the arrow keys or for the PgUp or PgDn key, it sends an appropriate 
scrolling message to the client window. Therefore, the scroll bar initi¬ 
ates scrolling activity in response to both the mouse and the keyboard. 
In the example program, however, there is one problem. As mentioned 
in the section on Creating the Scroll Bars, the client window is assigned 
the focus through the WinSetFocus function. Therefore, all keyboard 
messages are sent to the client window and are not received by the 
scroll bar windows. 

The solution to this problem is for the client window to reroute cer¬ 
tain keyboard messages to the appropriate—horizontal or vertical— 
scroll bar window. WM_CHAR messages are processed by the function 
Character in the example program, which is listed in Figure 4.21. This 
function calls WinSendMsg (Figure 4.8) to send all messages for the 
T, i, PgUp, or PgDn key to the vertical scroll bar, and all messages for 
the <— or —> key to the horizontal scroll bar. All other keys are simply 
ignored (the function returns FALSE, which tells the system that the key 
was not processed). 
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MRESULT EXPENTRY Character (HWND 
{ 

hwnd, USHORT msg, MPARAM mpl, MPARAM 

mp2) 


/*** Send arrow and PgUp/PgDn key 

messages 

to appropriate scroll bars 

*******, 

switch (CHARMSG (&msg)->vkey) 

/ 




case VK UP: 

/* 

Up-arrow key. 


V 

case VK DOWN: 

/* 

Down-arrow key. 


*/ 

case VK PAGEUP: 

/* 

Page Up key. 


V 

case VK_PAGEDOWN: 

/* 

Page Down key. 


V 

return WinSendMsg 

(HVScroll, 

msg, mpl, mp2); 



case VK LEFT: 

/* 

Left-arrow key. 


V 

case VK_RIGHT: 

/* 

Right-arrow key. 


*/ 

return WinSendMsg 

(HHScroll, 

msg, mpl, mp2); 



default: 





return FALSE; 

} 





} /* end Character */ 






• Figure 4.21: 

The function Character of the example program 


Note that the arrow and PgUp/PgDn keys are among the keystrokes 
identified by virtual codes (used to label keys that do not have simple 
ASCII character codes). The virtual code is contained in one of the mes¬ 
sage parameters, and it is extracted using the special macro for charac¬ 
ter messages, CHARMSG; virtual keys and the CHARMSG macro will 
be explained in Chapter 6. Table 4.4 lists the codes for each virtual key, 
the identity of the key, the scroll bar that is sent the key message, and 
the message that the scroll bar sends to the client window when it 
receives the key. 


• UPDATING THE WINDOW 

The WM_PAINT message is processed by the Paint function of the 
example program, which is listed in Figure 4.22. This function has been 
modified from the previous version so that it repaints only the invalid 
region of the window. Like the previous version. Paint begins by calling 
WinBeginPaint (Figure 2.20) to obtain a handle to a presentation space; 
however, instead of passing 0 as the last parameter, it passes the address 
of a RECTL structure (Rect; see Figure 2.22). WinBeginPaint assigns 
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+ Table 4A: The Virtual Keys Processed by the Scroll Bars 


Code 

_-_ ■■■-. 

Key 

Scroll Bar 

That Receives 
the Key 

Message Sent by 
Scroll Bar to 

Client Window 

VK_UP 

t 

Vertical 

WM_V SCROLL, 
SB_LINEUP 

VK_DOWN 

i 

Vertical 

WM VSCROLL, 
SB_LINEDOWN 

VK_PAGEUP 

PgUp 

Vertical 

WM_V SCROLL, 
SB_PAGEUP 

VK_PAGEDOWN 

PgDn 

Vertical 

WM VSCROLL, 
SB_PAGEDOWN 

VK.LEFT 

<— 

Horizontal 

WM_HSCROLL, 

SBJLINELEFT 

VKRIGHT 

-» 

Horizontal 

WM HSCROLL, 
SB_LINERIGHT 


this structure the dimensions of the invalid region of the client window. 
Accordingly, the subsequent call to the function WinFillRect (Figure 
2.23), which is passed the address of Reel, erases only the invalid area. 
(Note that the call to WinQueryWindowRect is no longer needed.) 

The program now calculates the range of file lines that need to be dis¬ 
played within the invalid area. StartLine is the first line in this range 
and StopLine is the last. These values are calculated as follows: 

StartLine = TopLine + (yWin - (SHORT)Rect.yTop) / 
yCharTot; 

StopLine = min (LastLine, TopLine + 

(yWin - (SHORT)Rect.yBottom) / yCharTot); 

StartLine is calculated by adding the number of lines above the begin¬ 
ning of the invalid region to TopLine (the number of the line displayed 
at the top of the window). StopLine is derived by adding the number of 
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MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


register int Line; 
HPS HPresSpace; 
RECTL Rect; 

SHORT StartLine; 
SHORT StopLine; 
POINTL Start; 

SHORT LineLength; 


/* Loop counter. 

/* Presentation space handle. 

/* Window coordinates, in window coordinates. 
/* First file line to paint. 

/* Last line to paint. 

/* Starting position to print string. 

/* Length of each line displayed. 


/*** Get presentation space and coordinates of invalid region in window. 
HPresSpace = WinBeginPaint 


(hwnd, 

/* 

0, 

/* 

&Rect); 

/* 

GpiCreateLogFont 

/* 

(HPresSpace, 

/* 

(PSTR8)NULL, 

/* 

ID_COURIER, 

/* 

&FontAttributes) 

; /* 

GpiSetCharSet 

/* 

(HPresSpace, 

/* 

ID_COURIER); 

/* 

Erase invalid region 

only. • 

WinFillRect 

(HPresSpace, 

/* 

&Rect, 

/* 

CLR WHITE); 

/* 

Set color used by 'GpiCharSI 

GpiSetColor 

(HPresSpace, 

/* 

CLR_BLACK); 

/* 


V 

V 

V 

V 
*/ 
*/ 

V 


/* Address of struct, to set to invalid region.*/ 


*/ 

*/ 

V 

V 


/*** calculate first and last lines to go in invalid region. *****************/ 

StartLine = TopLine + (yWin - (SHORT)Rect.yTop) / yCharTot; 

StopLine = min (LastLine, TopLine + (yWin - (SHORT)Rect.yBottom) 

/ yCharTot); 

/*** Print lines within invalid region. **************************************/ 


Start.y = yWin - yCharTot * (StartLine - TopLine + 1) + yCharDesc; 
Start.x = xChar * (-FirstCol); 

for (Line = StartLine; Line <= StopLine; ++Line, Start.y -= yCharTot) 

if ((LineLength = GetLineLength (Line)) == 0) 
continue; 

GpiCharStringAt /* Prints string at given position. 


Figure 4.22: 

The function Paint of the example program 
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(HPresSpace, /* Presentation space handle. _ */ 

&Start, /* Structure containing starting position.*/ 

(LONG)LineLength, /* Number of characters to print. */ 

GetLineAddr (Line));/* Address of line. */ 

} 

WinEndPaint (HPresSpace); 
return FALSE; 

) /* end Paint */ 


• Figure 4.22: 

The function Paint of the example program (continued) 

lines above the end of the invalid region to Topline; using the min 
macro, however, assures that StopLine will not be assigned a value 
larger than the number of the last line in the file (LastLine). 

Next, the program determines the pixel coordinates of the starting 
point of the first line to be displayed (at the top of the invalid region). 
The y-coordinate of the starting point, Start.y, is calculated as follows: 

Start.y = yWin - yCharTot * (StartLine - TopLine + 1) 

+ yCharDesc; 

To determine the x-coordinate of the starting point (Start.x), the pro¬ 
gram does not waste time calculating the horizontal pixel coordinate of 
the start of the invalid region and the offset of the character in the file 
line that needs to be displayed at this point. Rather, it takes advantage 
of the fact that the Presentation Manager automatically clips all charac¬ 
ters that fall outside of the invalid region, and the fact that you can safe¬ 
ly specify a starting point to the left of the bounds of the current 
window (by passing a negative x-coordinate). The following simple ex¬ 
pression does the trick: 

Start.x = xChar * (-FirstCol); 

Remember that FirstCol is the offset of the character within the file 
line that is to appear at the left edge of the window. The call to Gpi- 
CharStringAt, however, always specifies the address of the beginning 
of the line (the address of character 0 within this line). If FirstCol is 0, 
then Start.x is assigned 0, and character 0 gets printed at the left of the 
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window (pixel coordinate 0). If, however, FirstCol is 1, then character 0 
is printed one character space to the left of the window. This character, of 
course, is invisible; character 1, however, is printed at the left of the win¬ 
dow, and, if this position is within the invalid region, character 1 is 
visible. Values of FirstCol larger than 1 work similarly. Although only 
characters within the current invalid region are actually painted (the 
other regions within the window already contain the appropriate char¬ 
acters), the value assigned to Start.x assures that the characters printed 
are correctly aligned horizontally. 

The for loop that prints each line works in the same manner as the 
loop in the previous version of Paint. 


• ENHANCEMENTS 

As mentioned at the beginning of the chapter, the current version 
of the example program can be used as a practical utility for viewing 
text files within a Presentation Manager window. You might want to en¬ 
hance the program for this purpose by adding one or more of the fol¬ 
lowing features (the techniques are described in subsequent chapters): 

• The ability to read in a new file without restarting the program. 
This feature could be accessed through a menu item (Chapter 7) 
and the file name could be entered through a dialog box (Chap¬ 
ter 8). A file-reading routine is presented in Chapter 8. 

• A search feature for finding a specific string within the file. This 
facility could also be accessed through a menu item and a dialog 
box; an algorithm for searching for a string is presented in Chap¬ 
ter 8. 

• You could display the name of the current file within the title bar 
using the WinSetWindowText function. This technique is also 

presented in Chapter 8. 
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. CONCLUSION 

You can prepare the current version of the example program using 
the MAKE file listed in Figure 4.23. A linker definition file is given in 
Figure 4.24, and the complete source listing for the program is provided 
in Figure 4.25. 

This chapter has described how to use the facilities of the Presenta¬ 
tion Manager programming environment to view any portion of the file 
contained in the internal data buffer. Before presenting the methods for 
modifying and saving this data, however. Chapter 5 explores the tech¬ 
niques for creating and moving a cursor to any position within the file. 


# Figure 4.23 

# This MAKE file prepares the program of Figures 4.24 and 4.25 

# 

FIG4_2 5.OBJ : FIG4_25.C 

cl /W2 /c /Zp /G2ws FIG4_25.C 

FIG4 25.EXE : FIG4_25.0BJ FIG4_24.DEF 

link /NOD FIG4_25.0BJ,, NUL, OS2.LIB SLIBCE.LIB, FIG4_24.DEF 


© Figure 4.23: 

A MAKE file for preparing the example program 


; Figure 

4.24 

; Linker 

definition file for the program listed in Figure 4.25 

NAME 

FIG4 25 

PROTMODE 


HEAPSIZE 

1024 

STACKSIZE 

8192 

EXPORTS 

WndProc 


® Figure 4.24: 

A linker definition file for preparing the example program 
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/* 

Figure 4.25 

Version 3 of the Presentation Manager text editor example program. 

This version adds vertical and horizontal scroll bars that allow the user 
to scroll through the file using the mouse or the arrow and PgUp/PgDn keys. 
The program provides a handy utility for viewing text files. 


V 

#define INCL_GPI 
#define INCL_WIN 
#include <0S2.H> 
#include <STDIO.H> 
#include <PROCESS.H> 
#include <10.H> 
#include <STRING.H> 

#include <STDLIB.H> 


/* Include all Gpi... function declarations. */ 
/* Include all Win... function declarations. */ 

/* C library header files: */ 


/*** window procedure declaration. *******************************************/ 
MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


/*** Declarations / definitions for file- and buffer-management module. ******/ 


#define LINEBUFSIZ 255 /* Size of buffer for holding lines. */ 

#define ERROPEN 1 /* Error: opening file. */ 

#define ERRTOOBIG 2 /* Error: file too large. */ 

#define ERRMAXLINES 3 /* Error: maximum file lines exceeded. */ 

#define ERRALLOC 4 /* Error: heap allocation. */ 

void Buflnit (void); /* Initializes buffer management module. */ 

char *ErrorMessage (int ErrorNumber); /* Returns error message string. */ 

int ReadFile (char *FileName); /* Reads file into editor buffer. */ 

SHORT GetLineLength (int Line); /* Gets length of line in buffer. */ 

PCH GetLineAddr (int Line); /* Gets address of line in buffer. */ 

int LastLine = -1; /* Number of last line in buffer. */ 

HHEAP HHeap = NULL; /* PM heap handle. */ 

/*** utility function declarations. ******************************************/ 

void ErrorQuit (char ^Message); /* Print error message, end program. */ 

void Quit (int ErrorCode); /* Terminate the PM program. */ 

/*** Global variables. *******************************************************/ 

HWND HFrame; /* Handle to main frame window. */ 

HAB HAncBlk; /* Handle to anchor block. */ 

HMQ HMesQue; /* Message queue handle. */ 


Figure 425: 

The source codefile for the example program 
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void main (int argc, char *argv[]) 


int ReadError = 0; 

/* 

Error occurred reading file. 

V 

int UsageError = 0; 

/* 

No file name given on command line. 

*/ 

HWND HClient; 

/* 

Handle to main client window. 

*/ 

QMSG QueMess; 

/* 

Message structure. 

*/ 

ULONG CtlData = 

/* 

Control windows to include. 

*/ 

FCF HORZSCROLL 

/* 

Horizontal scroll bar. 

V 

FCF MINMAX 

/* 

Minimize/maximize box. 

V 

FCF SHELLPOSITION 

/* 

Make window visible on screen. 

*/ 

FCF SIZEBORDER 

/* 

Wide sizing border. 

*/ 

FCF SYSMENU 

/* 

System menu. 

*/ 

FCF TASKLIST 

/* 

Display program name in Task Manager. 

V 

FCF TITLEBAR 

/* 

Title bar. 

V 

FCF_VERTSCROLL? 

/* 

Vertical scroll bar. 

*/ 

Buflnit (); 




if (argc < 2) 





UsageError = 1; 


else 

ReadError = ReadFile (argv [1]); 


HAncBlk = Winlnitialize (0) ? 

HMesQue = WinCreateMsgQueue 

/* Initialize PM system for process. 

(HAncBlk,0); /* Create a message queue. 

V 

V 

WinRegisterClass 

/* 

Register procedure for main window. 

V 

(HAncBlk, 

/* 

Anchor block handle. 

*/ 

"MAIN", 

/* 

Window class name. 

*/ 

WndProc, 

/* 

Window procedure associated w/ class. 

*/ 

0L, 

/* 

Class style. 

V 

0) ; 

/* 

Extra storage bytes. 

V 

HFrame = WinCreateStdWindow 

/* 

Create parent window. 

V 

(HWND DESKTOP, 

/* 

Parent window handle. 

*/ 

WS_VISIBLE, 

/* 

Frame window style. 

V 

&CtlData, 

/* 

Address of control data. 

*/ 

"MAIN", 

/* 

Client window class name. 

V 

o PM Text Editor", 

/* 

Text for title bar. 

*/ 

0L, 

/* 

Client window style. 

*/ 

o, 

/* 

Resource module handle. 

*/ 

o. 

/* 

Resource identification. 

V 

&HClient)? 

/* 

Address to receive client window hand. 

V 


if (UsageError) 

ErrorQuit ("Must specify file name."); 
if (ReadError) 

ErrorQuit (ErrorMessage (ReadError) ) ; 

/*** Give focus to client window. ********************************************/ 
WinSetFocus 

(HWND_DESKTOP / /* Handle for desktop window. */ 

HClient); /* Client window handle. */ 


• Figure 4.25: 

The source codefile for the example program (continued) 






while (WinGetMsg /* Get messages until WM_QUIT. */ 

(HAncBlk, /* Anchor block handle. */ 

&QueMess, /* Address of message structure. */ 

0, /* Window filter. */ 

0, /* First message identifier. */ 

0)) /* Last message identifier. */ 

WinDispatchMsg (HAncBlk,&QueMess); /* Dispatch messages. */ 


Quit (0); 

} /* end main */ 


/*** window procedure and subroutines. ***************************************/ 

MRESULT EXPENTRY Character (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY HScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 
MRESULT EXPENTRY VScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


static SHORT xChar; /* Character width. */ 
static SHORT yCharTot; /* Total height of characters. */ 
static SHORT yCharDesc; /* Height of character descenders. */ 
static SHORT xWin; /* Horizontal size of window. */ 
static SHORT yWin; /* Vertical size of window. */ 
static HWND HVScroll; /* Handle to vertical scroll bar window. */ 
static HWND HHScroll; /* Handle to horizontal scroll bar window. */ 
static int FirstCol; /* Character to be in first column position. */ 
static int FirstColMax; /* Maximum value of 'FirstCol'. */ 
static SHORT TopLine =0; /* Number of top line in window. */ 
static SHORT TopLineMax; /* Maximum value of 'TopLine'. */ 
static FATTRS FontAttributes; /* Stores font attributes from GpiQueryFonts. */ 

#define ID_COURIER 99L /* Local font ID. */ 
MRESULT EXPENTRY WndProc 

(HWND hwnd, /* Window handle. */ 
USHORT msg, /* The message. */ 
MPARAM mpl, /* Message-specific information. */ 
MPARAM mp2) /* Message-specific information. */ 


{ 

switch (msg) 

{ 

case WM_CHAR: /* Message sent when keyboard key is received. */ 

return Character (hwnd, msg, mpl, mp2); 

case WM_CREATE: /* Message sent when window is first created. */ 

return Create (hwnd, msg, mpl, mp2); 

case WM_HSCROLL: /* Message sent on horizontal scroll activity. */ 


Figure 4.25: 

The source code file for the example program (continued) 
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return HScroll (hwnd, msg, mpl, mp2); 

case WM_PAINT: /* Message sent when window data is invalid. */ 

return Paint (hwnd, msg, mpl, mp2); 

case WM_SIZE: /* Message sent whenever window changes size. */ 

return Size (hwnd, msg, mpl, mp2); 

case WM_VSCROLL: /* Message sent on vertical scroll activity. */ 

return VScroll (hwnd, msg, mpl, mp2); 

default: /* Perform default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} /* end switch */ 

} /* end WndProc */ 

/*** subroutines called by window procedure. *********************************/ 

MRESULT EXPENTRY Character (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

/*** Send arrow and PgUp/PgDn key messages to appropriate scroll bars. *******/ 


Up-arrow key. 
Down-arrow key. 
Page Up key. 

Page Down key. 

, msg, mpl, mp2); 
Left-arrow key. 
Right-arrow key. 
, msg, mpl, mp2); 


switch (CHARMSG (&msg)->vkey) 

{ 

case VK_UP: /* 

case VK_DOWN: /* 

case VK_PAGEUP: /* 

case VK_PAGE DOWN: /* 

return WinSendMsg (HVScroll 
case VK_LEFT: /* 

case VK_RIGHT: /* 

return WinSendMsg (HHScroll 
default: 

return FALSE; 

} 

} /* end Character */ 


MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

HPS HPresSpace; /* Presentation space handle. 

FONTMETRICS Metrics; /* Structure to hold font dimensions. 

LONG NumberStructs = 1; /* Number of structures from GpiQueryFonts. 

GpiLoadFonts /* Load Courier font. 

(HAncBlk, /* Anchor block handle. 

''\\0S2\\DLL\\C0URIER. FON") ; /* Full path name of font file. 

HPresSpace = WinGetPS (hwnd); 


Figure 425: 

The source code file for the example program (continued) 
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GpiQueryFonts 

(HPresSpace, 
QF_PRIVATE, 
"Courier", 
&NumberStructs, 


/* Obtain information on Courier font. */ 
/* Handle to presentation space. */ 
/* Enumerate private fonts. */ 
/* Font face name. */ 
/*_Number_of FONTMETRICS structures returned. */ 


(long)sizeof (FONTMETRICS),/* Length of structure for EACH font. 
^Metrics); /* Address of FONTMETRICS structure(s). * */ 

xChar = (SHORT)Metrics.lAveCharWidth; 

yCharTot = (SHORT)Metrics.IMaxBaselineExt; 
yCharDesc = (SHORT)Metrics.IMaxDescender; 

FontAttributes.usRecordLength = sizeof (FontAttributes); 

FontAttributes.fsSelection = Metrics.fsSelection; 

FontAttributes.IMatch = Metrics.IMatch; 

strcpy (FontAttributes.szFacename,Metrics.szFacename); 

FontAttributes.idRegistry = Metrics.idRegistry; 

FontAttributes.usCodePage = Metrics.usCodePage; 

FontAttributes.IMaxBaselineExt = Metrics.IMaxBaselineExt; 

FontAttributes.lAveCharWidth = Metrics.lAveCharWidth; 

FontAttributes.fsType = FATTR_TYPE_FIXED; 

FontAttributes.fsFontUse = 0 ; 

WinReleasePS (HPresSpace); 

/*** Get handles to horizontal and vertical scroll bar windows. **************/ 


QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 

/* Identifier for vertical scroll bar. */ 


QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 

/* Identifier for vertical scroll bar. */ 


HHScroll = WinWindowFromID 
(WinQueryWindow (hwnd, 

FID_HORZSCROLL) ; 

HVScroll = WinWindowFromID 
(WinQueryWindow (hwnd, 

FID_VERTSCROLL); 

return FALSE; 

} /* end Create */ 


MRESULT EXPENTRY HScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

SHORT Delta; /* Amount to scroll. 

/*** Determine amount to scroll. *********************************************/ 

switch (SH0RT2FR0MMP (mp2)) /* Switch on code from scroll bar. */ 

case SB_LINELEFT: 

Delta = -1; 
break; 

case SB_LINERIGHT: 

Delta = 1; 
break; 

case SB_PAGELEFT: 

Delta = -6; 
break; 


/ 


• Figure 4.25: 
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case SB_PAGERIGHT: 

Delta = 6; 
break; 

case SB_SLIDERPOSITION: 

Delta = SH0RT1FR0MMP (mp2) - FirstCol; 
break; 
default: 

Delta = 0; 
break; 

Deltamax (-FirstCol, min (Delta,FirstColMax - FirstCol)); 

/*** Scroll the window if necessary. *****************************************/ 
if (Delta) 

/*** Adjust first column value. ************************************/ 
FirstCol += Delta; 

/*** scroll the window data. ***************************************/ 
WinScrollWindow 

(hwnd, /* Handle of client window. */ 

-Delta * xChar, /* Horizontal scroll amount. */ 

0, /* Vertical scroll amount. */ 

0, /* Must be 0. */ 

0, /* Must be 0. */ 

0, /* Must be 0. */ 

0, /* Must be 0. */ 

SW_INVALIDATERGN); /* Invalidate "exposed" region. */ 


/*** Force repainting of invalid window region. ********************/ 
WinUpdateWindow 

(hwnd); /* Handle of client window. */ 

/*** Update the position of the horizontal scroll bar slider. ******/ 
WinSendMsg 

(HHScroll, /* Handle to horizontal scroll bar. */ 

SBM_SETPOS, /* Set position of slider. */ 

MPFROM2SHORT (FirstCol,0), /* Current position. */ 

0) ; /* Second parameter n/a. */ 


return FALSE; 


} /* end HScroll */ 


MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


register int Line; 
HPS HPresSpace; 
RECTL Rect; 

SHORT StartLine; 
SHORT StopLine; 
POINTL Start; 

SHORT LineLength; 


/* Loop counter. 

/* Presentation space handle. 

/* Window coordinates, in window coordinates. 
/* First file line to paint. 

/* Last line to paint. 

/* Starting position to print string. 

/* Length of each line displayed. 


/*** Get presentation space and coordinates of invalid region in window. 


• Figure 4.25: 
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HPresSpace = WinBeginPaint 


(hwnd, 

/* 

0, 

/* 

&Rect) ; 

/* 

GpiCreateLogFont 

/* 

(HPresSpace, 

/* 

(PSTR8)NULL, 

/* 

ID_C0URIER, 

/* 

&FontAttributes) 

; /* 

GpiSetCharSet 

/* 

(HPresSpace, 

/* 

ID_COURIER); 

/* 

Erase invalid region 

only. ■ 

WinFillRect 

(HPresSpace, 

/* 

&Rect, 

/* 

CLR_WHITE); 

/* 

Set color used by 'GpiCharS- 

GpiSetColor 

(HPresSpace, 

/* 

CLR_BLACK); 

/* 


tsentation space handle. */ 

•ucture containing window coordinates. */ 
or to use (white). */ 

igAt'. ************************************/ 

isentation space handle. */ 

.or to use: black. */ 

/*** Calculate first and last lines to go in invalid region. *****************/ 

StartLine = TopLine + (yWin - (SHORT)Rect.yTop) / yCharTot; 

StopLine = min (LastLine, TopLine + (yWin - (SHORT)Rect.yBottom) 

/ yCharTot); 

/*** Print lines within invalid region. **************************************/ 

Start.y = yWin - yCharTot * (StartLine - TopLine +1) + yCharDesc; 

Start.x = xChar * (-FirstCol); 

for (Line = StartLine; Line <= StopLine; ++Line, Start.y -= yCharTot) 

( 

if ((LineLength = GetLineLength (Line)) == 0) 
continue; 

GpiCharStringAt /* Prints string at given position. */ 

(HPresSpace, /* Presentation space handle. */ 

SStart, /* Structure containing starting position.*/ 

(LONG)LineLength, /* Number of characters to print. */ 

GetLineAddr (Line));/* Address of line. */ 

} 

WinEndPaint (HPresSpace); 
return FALSE; 

} /* end Paint */ 

MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 
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/*** obtain vertical and horizontal dimensions of client window. *************/ 


yWin = SH0RT2FROMMP (mp2) ; 
xWin = SHORT1FR0MMP (mp2); 

/*** Update 'TopLineMax' and 'TopLine'. **************************************/ 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

TopLine = min (TopLine,TopLineMax); 

/*** Adjust range and position of vertical scroll bar slider. ****************/ 

WinSendMsg /* Send window message. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

/*** Enable scroll bar only if needed (TopLineMax > 0). **********************/ 

WinEnableWindow 

(HVScroll, /* Recipient handle: horizontal scroll bar*/ 

TopLineMax ? TRUE : FALSE); /* Enable only if max. != 0. */ 

/*** Update 'FirstColMax' and 'FirstCol'. ************************************/ 

FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 

FirstCol = min (FirstCol, FirstColMax); 

/*** Adjust range and position of horizontal scroll bar slider. **************/ 


WinSendMsg /* Send message. 

(HHScroll, /* Recipient handle: vertical sc] 

SBM_SETSCROLLBAR, /* Set position & range. 

MPFR0M2SHORT (FirstCol, 0), /* Position. 

MPFR0M2SHORT (0, FirstColMax)); /* Range. 


/* Recipient handle: vertical scroll bar. */ 


return FALSE; 


} /* end Size */ 


MRESULT EXPENTRY VScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


SHORT Delta; 


/* Amount to scroll. 


/*** Determine amount to scroll. *********************************************/ 

switch (SH0RT2FROMMP (mp2)) /* Switch on code from scroll bar. */ 

{ 

case SB_LINEUP: 

Delta = -1; 
break; 

case SB_LINEDOWN: 

Delta = 1; 
break; 


® Figure 4.25: 
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case SB_PAGEUP: 

Delta = -yWin / yCharTot; 
break; 

case SB_PAGEDOWN: 

Delta = yWin / yCharTot; 
break; 

case SB_SLIDERPOSITION: 

Delta = SHORT1FR0MMP (mp2) - TopLine; 
break; 
default: 

Delta = 0; 
break; 

} 

Delta = max (-TopLine, min (Delta,TopLineMax - TopLine)); 

/*** Scroll the window if necessary. *****************************************/ 

if (Delta) 

{ 

/*** Adjust top line value. ****************************************/ 
TopLine += Delta; 

/*** Scroll the window data. ***************************************/ 
WinscrollWindow 



(hwnd, 


/* 

Handle of client window. 

*/ 


0 , 


/* 

Horizontal scroll amount. 

*/ 


yCharTot * Delta, 


/* 

Vertical scroll amount. 

*/ 


0 , 


/* 

Must be 0. 

*/ 


0, 


/* 

Must be 0. 

*/ 


o, 


/* 

Must be 0. 

*/ 


o, 


/* 

Must be 0. 

*/ 


SW_INVALIDATERGN); 


/* 

Invalidate "exposed" region. 

*/ 

/*** 

Force repainting of 

invalid 

window region. ********************/ 

WinUpdateWindow 






(hwnd); 


/* 

Handle of client window. 

*/ 

/ "k -k 

Update the position 

of 

the vertical scroll bar slider. ********/ 

WinSendMsg 






(HVScroll, 


/* 

Handle to vertical scroll bar. 

*/ 


SBM_SETPOS, 


/* 

Set position of slider. 

*/ 


MPFROM2SHORT (TopLine, 

0) ,/* 

Current position. 

*/ 


o) ; 


/* 

Second parameter n/a. 

*/ 


} 

return FALSE; 

} /* end VScroll */ 

/*** Buffer- and file-management module ***************************************/ 
#define MAXLINES 4096 /* Maximum number of lines in buffer. */ 

/* Stores information on each line. */ 


static struct 

{ 


PCH LineAddress; 
unsigned char LineLength; 


/* Far address of block containing line. */ 
/* Length of line (includes \n and \0) . */ 


Figure 4.25: 
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• Figure 425: 

The source code file for the example program (continued) 







9 196 Programmer's Guide to the OS/2 Presentation Manager 


if (FileLength > 50000) 
return (ERRTOOBIG); 


/* Make heap 20% larger than file size. */ 

HeapSize = (USHORT)(FileLength + FileLength / 5); 

HHeap = WinCreateHeap /* Allocate a heap for file data. */ 

(0, /* Segment address: 0 means allocate new segment. */ 

HeapSize, /* Initial heap size. */ 

0, /* Minimum increase size: 0 means use default. */ 

0, /* Minimum # of dedicated free lists: none. */ 

0, /* Maximum # of dedicated free lists: none. */ 

0); /* Options: none. */ 

FarPtr = WinLockHeap (HHeap); /* Get heap segment selector. */ 

HeapSelector = SELECTOROF (FarPtr); 

/* Read each line in file into a separate block allocated from heap. */ 
LastLine = -1; 

while (fgets (LineBuffer,LINEBUFSIZ-1,PtrFile) != NULL) 

{ 

/* Test for line limit -- update 'LastLine'. */ 

if (++LastLine >= MAXLINES) 
return (ERRMAXLINES); 

/* Calculate length of line. */ 

LineLength = (unsigned char)strlen (LineBuffer) + 1;/* Include null*/ 

/* Insert '\n' into overlength lines. */ 

if (LineLength == LINEBUFSIZ - 1 && 

LineBuffer [LINEBUFSIZ - 3] != '\n') 


LineBuffer [LINEBUFSIZ - 2] = '\n'; 
LineBuffer [LINEBUFSIZ - 1] = '\0'; 
++LineLength; 

) 


/* Allocate a block from heap to hold the line. */ 

HeapOffset = WinAllocMem 

(HHeap, /* Heap handle. */ 

LineLength); /* Length of line to store. */ 

if (HeapOffset == NULL) 
return (ERRALLOC); 

/* Copy line into heap block. */ 

movedata (Lineselector,LineOffset,HeapSelector, 

(unsigned)HeapOffset,LineLength); 

/* Insert line information into the table. */ 


LineTable [LastLine].LineAddress = MAKEP (HeapSelector,HeapOffset); 
LineTable [LastLine].LineLength = LineLength; 

) 

fclose (PtrFile); /* Close the file. */ 

return (0); 

} /* end of ReadFile */ 
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SHORT GetLineLength (int Line) /* Gets length of line in buffer. */ 

{ 

if (Line < 0 || Line > LastLine) 
return 0; 

else 

/* Extract line length from table, excluding '\n' and '\0'. */ 

return LineTable [Line].LineLength - 2; 

} /* end GetLineLength */ 


PCH GetLineAddr (int Line) /* Gets address of buffer line. */ 

{ 

if (Line < 0 || Line > LastLine) 
return NULL; 

else 

return LineTable [Line].LineAddress; 

} /* end GetLineAddr */ 


/*** utility functions. ******************************************************/ 

void ErrorQuit /* Terminate program due to fatal error condition. */ 

(char *Message) /* Error message to display to user. */ 

{ 

char Buffer [60]; 


sprintf (Buffer,"Program Error: %s",Message); 


WinMessageBox 

/* 

Display a message box. 

*/ 


(HWND_DESKTOP, 

/* 

Handle of parent: desktop window. 

*/ 


HFrame, 

/* 

Handle of owner: frame window. 

*/ 


Buffer, 

/* 

Message text. 

V 


"PM Text Editor", 

/* 

Caption. 

*/ 


0, 

/* 

Help window ID: not needed. 

V 


MB OK | 

/* 

Display an 'OK' button. 

V 


MB_ICONHAND); 

/* 

Display a hand icon. 

V 

Quit 

(i) ; 

/* 

Call normal termination function. 

*/ 

} /* 

end ErrorQuit */ 




void Quit 





(int 

ErrorCode) /* 

Process termination status. 

*/ 


/* 

Calls Presentation Manager termination functions and ends program 
with specified error code. 


*/ 

{ 

if (HHeap 1= NULL) 

WinDestroyHeap (HHeap); 
WinDestroyWindow (HFrame); 
WinDestroyMsgQueue (HMesQue); 
WinTerminate (HAncBlk); 
exit (ErrorCode); 

} /* end Quit */ 


® Figure 4.25: 
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his chapter adds a cursor to the emerging Presentation 
Manager text editor. The cursor serves to mark the cur¬ 
rent insertion point within the file, which is the position 
where characters will be either inserted or deleted in 
later versions of the program. The code presented in this chapter creates 
a cursor and places it initially at the upper left corner of the screen; you 
can then use the arrow keys to move the cursor within the window. The 
arrow keys thus are no longer used for directly scrolling the file; how¬ 
ever, if you move the cursor beyond the current edges of the window, 
the contents of the screen are scrolled to reveal additional file lines or 
columns. Thus, the cursor functions indirectly as a scrolling mecha¬ 
nism. This chapter also presents routines for using the Home and End 
keys to reposition the cursor at the beginning or end of the line. The 
PgUp and PgDn keys, as well as the horizontal and vertical scroll bars, 
serve the same function as in the previous version of the program. 

In this chapter you will learn how to create, maintain, and move the 
cursor. You may be surprised that an entire chapter is required to ex¬ 
plain the logic of the cursor; under the Presentation Manager, however, 
managing the cursor is much more complex than in traditional 
programming environments, for several reasons. First, you must ex¬ 
plicitly create the cursor each time the client window obtains the input 
focus, and destroy the cursor whenever the window loses the focus. 
Also, you must adjust the cursor position each time the window chan¬ 
ges size; and finally, you must explicitly reposition the cursor whenever 
the user scrolls the window, moves the cursor, or inserts, overwrites, or 
deletes characters. 

This chapter lists all of the basic routines required to manage the cur¬ 
sor. You can incorporate these additions into the previous version of the 
text editor to obtain a program that displays a file and allows you to 
move the cursor to any position within this file. The complete listing of 
the current version of the example program is given in Figure 6.24, at 
the end of Chapter 6. This listing incorporates all of the features dis¬ 
cussed in the current chapter, plus the full keyboard interface and 
routines for editing the file that are presented in Chapter 6. 
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• CREATING THE CURSOR 

Since the cursor marks the current position where characters may 
be entered from the keyboard, only the window that owns the input 
focus should display a cursor. As explained in Chapter 4, the window 
with the focus is the one that receives all messages for keyboard input. 
A window that employs a cursor, therefore, should create the cursor 
each time the window receives the focus, and it should destroy the cur¬ 
sor each time it loses the focus. 

Fortunately, the system sends the client window a message, 
WM_SETFOCUS, each time this window either receives or loses the 
focus. This message is accompanied by a flag (in the parameter mp2), 
which is nonzero if the window is receiving the focus and zero if the 
focus is being taken away Remember that the function main calls Win- 
SetFocus to explicitly pass the focus to the client window before it 
enters the main message loop; therefore, WMSETFOCUS (with the 
receiving flag set) is among the initial messages sent to the client win¬ 
dow immediately after it is created. The initial messages processed by 
the example program are sent in the following order: 

1. WMCREATE 

2. WM_SIZE 

3. WM_SETFOCUS (mp2 is set, indicating that the focus is being 
received) 

4. WM_PAINT 

Subsequently, the system sends the WM_SETFOCUS message when¬ 
ever the user either changes the focus to another window (for example, 
by selecting another application with the Alt-Esc key or by clicking on 
another window with the mouse), or restores the focus to the client win¬ 
dow. The WM_SETFOCUS message is explained in Figure 5.1. 

The example program processes the WMJ3ETFOCUS message in the 
function SetFocus, listed in Figure 5.2. The basic logic of this routine is 
simple: if the focus is being gained, it creates a cursor, and if the focus is 
being lost, it destroys the cursor. 

SetFocus creates the cursor by calling the WinCreateCursor Presen¬ 
tation Manager function (Figure 5.3). The program passes the handle 
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WM.SETFOCUS 

| 

Purpose: 


Sent by the system to a window whenever it is about to 
receive or lose the input focus. 

Parameters: 


MPARAM mpl 

If the focus is being received, contains the 
handle of the window that previously 
owned the focus, or NULL if no 
window owned the focus. If the focus is 


being lost, contains the handle of the 
window that is receiving the focus, or NULL 
if no window is receiving the focus. 

MPAR&M mp2 

TRUE if the window is receiving the focus, or 
FALSE if the window is losing the focus. 

Return Value: 


FALSE. 



• Figure 5.1: 

The WM_SETFOCUS Presentation Manager message 


hwnd as the first parameter so that the cursor will be displayed within 
the client window. The second two parameters specify the initial posi¬ 
tion of the cursor with respect to this window. These values are given in 
pixel coordinates, which are the same units used to specify the dimen¬ 
sions of the window, the metrics of the character font, and the starting 
positions of strings printed within the window. The cursor-position 
coordinates specify the location of the lower left pixel of the cursor. 
Note that these values specify a position within the standard window 
coordinate system illustrated in Figure 3.27, in which the origin (the 
position x=0, y=0) is at the lower left corner of the window. 

The program maintains two global variables, CursorLine and 
CursorCol, which store the current row and column position of the 
character associated with the cursor (which is displayed immediately to 
the right of the cursor; the cursor shape and position will be explained 
shortly). Note that the row and column positions in CursorLine and 






MRESULT EXPENTRY SetFocus (HWND hwnd, USHORT msg, MPARAM mpl, MPARAJM mp2) 

{ 

/*** If client window is RECEIVING focus, create cursor. *********************/ 


if (LONGFROMMP (mp2)) 

{ _ 

WinCreateCursor /* Create a new cursor. */ 

(hwnd, /* Client window handle. */ 

(Cursored - FirstCol) * xChar, /* x position of cursor. */ 
yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 
0/ /* x size of cursor: nominal border. */ 

yCharTot, /* y size of cursor. */ 

CURSOR_SOLID | /* Solid cursor. */ 

CURSOR_FLASH, . /* Flashing cursor. */ 

NULL); /* Clipping rectangle: entire window.*/ 


/*** Make the cursor visible. *******************************************/ 
WinShowCursor 



• Figure 5.2: 

The function SetFocus of the example program 


CursorCol refer to the location of the associated character within the file 
buffer, and not the character's position within the window. These two 
variables are initialized to 0, so that the cursor is initially associated 
with the first character in the file (rows and columns within the file are 
numbered beginning with 0). Since the position of the cursor on the 
screen passed to WinCreateCursor must be specified in pixel units, the 
row and column positions are converted to absolute pixel coordinates 
within the window. The horizontal coordinate is calculated using the 
expression 

(CursorCol - FirstCol) * xChar 

and the vertical coordinate is calculated with the expression 

yWin - (CursorLine - TopLine +1) * yCharTot 
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Note that these expressions yield the window coordinates of the 
lower left corner of the corresponding file character (below the baseline). 
The next two parameters (cx and cy) give the width and height of the 
cursor, also in pixel units. By passing a value of 0 for the horizontal 
dimension, the program specifies the nominal system border width , which 


WinCreateCursor 

Purpose: 

Creates a cursor within the specified window. 
Prototype: 

BOOL APIENTRY WinCreateCursor 


(HWND 

hwnd, 

Handle of window to have the cursor. 

SHORT 

X, 

Horizontal position of cursor within the 
window. 

SHORT 

y f 

Vertical position of cursor within the 
window. 

SHORT 

cx, 

Width of cursor; 0 means to use the 
nominal system border width. 

SHORT 

cy, 

Height of cursor; 0 means to use the 
nominal system border height. 

USHORT fs, 

The cursor style; you may combine one or 
more of the following values: 


Value 

CURSOR_SOLID 

CURSOR_HALF- 

TONE 

CURSOR_RECT 

CURSOR_FRAME 

CURSOR_FLASH 


Meaning 
Solid cursor 
Halftone cursor 

Solid rectan¬ 
gular cursor 

Rectangular 
frame cursor 

Blinking cursor 


• Figure 53: 

The WinCreateCursor Presentation Manager function 
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CURSOR_SETPOS Sets a new cur¬ 
sor position (as¬ 
sumes that a 
cursor has al¬ 
ready been 
created); causes 
function to ig¬ 
nore all other 
styles and the cx 
and cy 
parameters 

prectl prciciip) ; Points to a RECTL structure (defined in 
Figure 2.22) containing the dimensions of 
a rectangle within which the cursor is 
visible (a clipping rectangle); if the cursor 
moves outside this rectangle, it becomes 
invisible. A value of NULL sets the 
clipping rectangle to the entire 
dimensions of the window. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

When the cursor is first created it is invisible; you must call 
WinShowCursor to make it visible. A window should create 
a cursor whenever it receives the focus, and it should destroy 
the cursor (WinDes troy Cursor) whenever it loses the focus. 

Related Functions: 

WinDestroyCursor (Figure 5.6) 

WinShowCursor (Figure 5.5) 


• Figure 5.3: 

The WinCreateCursor Presentation Manager function (continued) 
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is a system-defined value (SV_CXBORDER) that yields a narrow 
but easily visible cursor. The program passes a height value of yChar- 
Tot so that the cursor is given the maximum character height. 
The next parameter—rgf, the cursor style—is assigned the value 
CURSOR_SOLID, for a solid rectangular cursor, combined with 
CURSOR_FLASH, for a blinking cursor. 

The resulting cursor is a narrow, blinking vertical bar, displayed at 
the left edge of the cell containing the associated character (which has a 
width of xChar and a height of yCharTot). Since the cursor is narrow, it 
falls totally within the area of this rectangle reserved for the blank space 
between characters, and does not overlap the pixels used to form nor¬ 
mal alphanumeric characters. Consequently, the cursor appears on the 
screen as a vertical bar between two characters. As explained, the file 
coordinates CursorLine and CursorCol refer to the character to the right, 
which in this book is termed the associated character. In subsequent ver¬ 
sions of the program, the Del key will erase the associated character to the 
right of the cursor, leaving the cursor in its present position; the Backspace 
key will delete the character to the left and move the cursor one space left; 
and a new character entered from the keyboard will be inserted to the left, 
causing the cursor to move one space right. Figure 5.4 illustrates the cursor 
and its relation to the surrounding characters. 

The cursor used by the example program thus differs from conven¬ 
tional cursors, which either underlie the associated character or high¬ 
light the entire area occupied by this character. The program cursor 
conforms to the Presentation Manager concept of a cursor as a marker 
indicating an insertion point rather than a character; in fact, the 
documentation often refers to the cursor as a caret , which is a 
proofreader's symbol typically placed between characters. 

A note regarding style: The cursor is an example of a Presentation 
Manager feature that can be created using a wide variety of styles. The 
developers of the Presentation Manager, however, have defined a set of 
application style guidelines that recommend which of the many pos¬ 
sible design options should be selected for particular situations. It is 
wise to conform to the standard style, since one of the primary benefits 
of Presentation Manager programs is that they provide a uniform—and 
therefore easily learned—user interface. This book follows these 
guidelines whenever practical; accordingly, the strong resemblance be¬ 
tween the example program and standard Presentation Manager and 
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Windows applications (such as the Windows Notepad editor) is neither 
coincidence nor blind imitation. (See the Microsoft Windows Application 
Style Guide, cited in the Bibliography.) 

The program cursor created by the call to WinCreateCursor has all 
the desired attributes, except that it is not yet visible. To make the cursor 



Figure 5.4: 

The cursor created by the example program 
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visible, the program calls the function WinShowCursor (Figure 5.5), 
passing a value of TRUE as the second parameter (you can assign a 
value of FALSE to temporarily hide a visible cursor). 

Finally, if the client window is losing the focus (mp2 is zero). Set- 
Focus destroys the cursor formerly created by WinCreateCursor. The 
cursor is destroyed by calling the Presentation Manager function Win- 
DestroyCursor (Figure 5.6), passing it the handle of the associated win¬ 
dow (hwnd, the client window). 


WinShowCursor 

Purpose: 

Makes visible or hides the cursor associated with the 
specified window. 

Prototype: 

BOOL APIENTRY WinShowCursor 
(hwnd hwnd, Handle of the window owning the cursor 

(created by calling WinCreateCursor). 
bool f show) ; A value of TRUE causes the function to 

make the cursor visible, and a value of 
FALSE causes it to hide the cursor. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Related Functions: 

WinCreateCursor (Figure 5.3) 


• Figure 55: 

The WinShowCursor Presentation Manager function 
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WinOestroy Cursor 

Purpose: 

Destroys the cursor associated with the specified window. 
Prototype: 

BOOL APIENTRY WinDestroyCursor 
(hwnd hwnd) ; Handle of the window owning the cursor 

(created by calling WinCreateCursor). 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Related Functions: 

WinCreateCursor (Figure 5.3) 

@ Figure 5.6: 

The WinDestroyCursor Presentation Manager function 


• MAINTAINING THE CURSOR 

Not only must the program create the cursor each time the win¬ 
dow gains the focus and destroy it when it loses the focus, but it must 
also maintain the cursor as the window changes size. This section 
describes the routines for maintaining the cursor that are added to the 
function Size, which processes the WM_SIZE message sent by the sys¬ 
tem whenever the dimensions of the window change. 


Keeping the Insertion Point 
within the Window 

When you reduce the size of the window, it is quite possible for the 
character associated with the cursor to fall outside the block of file data 
currently displayed within the window. This chapter adds a routine to 
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the Size function that automatically scrolls the file data, if necessary, so 
that the insertion point always remains visible within the window. This 
code is listed in Figure 5.7; note that the flag Update is defined and ini¬ 
tialized within the Size function as follows: 

int Update = 0 ; 

The routine first determines whether the line containing the cursor 
(CursorLine) falls below the last line visible in the window. If this condi¬ 
tion is true, it adjusts the top line displayed in the window (TopLine) so 
that CursorLine falls just inside the lower window boundary. Similarly, 
the program tests whether the cursor falls to the right of the visible por¬ 
tion of the file, adjusting FirstCol if necessary. If either of these adjust¬ 
ments is made (indicated by setting the Update flag), the program 
explicitly invalidates the entire window by calling the Presentation 
Manager function WinlnvalidateRect (Figure 5.8). 

Invalidating a region of a window—or the entire window—through 
the WinlnvalidateRect function causes the system to send a 
WM_PAINT message to the window procedure to give it an oppor¬ 
tunity to repaint the invalid area. As described in Chapter 4 (in the sec¬ 
tion on The WMJHSCROLL Message), this function provides a slow 


/*** Scroll window if necessary so that cursor position is visible. **********/ 

if (CursorLine >= TopLine + yWin / yCharTot) 

{ 

TopLine = CursorLine - yWin / yCharTot + 1? 

Update = 1; 

} 

if (Cursored >= FirstCol + xWin / xChar) 

{ 

FirstCol = CursorCol - xWin / xChar + 1; 

Update = 1; 

} 

if (Update) 

WinlnvalidateRect 

(hwnd, /* Client window handle. */ 

0, /* Rectangle: 0 means whole window. */ 

FALSE); /* Do not automatically include children. */ 


@ Figure 5.7: 

The routine for keeping the insertion point within the window 






WinlnvalidateRect 


Purpose: 

Adds a rectangular area to a window's update region. 

Prototype: 

BOOL APIENTRY WinlnvalidateRect 
(hwnd hwnd, Handle of the window to have 

its update region modified. 

prectl prci, Pointer to a RECTL structure 

containing the coordinates of 
the rectangle to add to the 
window's update region (the 
RECTL structure is defined in 
Figure 2.22); a value of NULL 
means to invalidate the entire 
window. 

BOOL f IncludeChildren) ; If this flag is TRUE, the 

function will always include 
descendants of hwnd in the 
invalid region; if FALSE, the 
function will include 
descendants in the invalid 
region unless the window was 
created with the 
WS CLIPCHILDREN style. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

Invalidating a region of a window will cause the system to 
send a WM_PAINT message to give the window the oppor¬ 
tunity to repaint this region. 

• Figure 5.8: 

The WinlnvalidateRect Presentation Manager function 







Controlling the Cursor 211 • 


but simple mechanism for scrolling the contents of the window. Since 
resizing operations are not performed in rapid succession like scrolling 
operations when you hold down an arrow key, the speed of this ap¬ 
proach is sufficient for the Size function. 


Recreating the Cursor 

When the program creates a cursor, it specifies a location within 
the window where the cursor is to be displayed. Each time the window 
changes size, the system dutifully maintains the cursor at this same win¬ 
dow location. Remember, however, that the cursor coordinates are 
specified with respect to the lower left corner of the window; in contrast, 
the text displayed within the window is always aligned with the upper 
left corner. Consequently, when the window is reduced in height, the 
vertical window coordinates of all characters still visible within the 
window are diminished by the amount of the window reduction so that 
the characters remain the same distance from the top of the window. 
Since the cursor coordinates remain the same, the cursor no longer ap¬ 
pears next to its associated character after the window is resized. 

Accordingly, the routine that processes the WM_SIZE message (the 
function Size in the example program) must recalculate the cursor coor¬ 
dinates for the new window size, and reposition the cursor by calling 
the function WinCreateCursor (as you will see in the next section, you 
can call WinCreateCursor not only to create a new cursor, but also to 
resize an existing cursor). However, another problem remains: the cur¬ 
sor clipping rectangle. The cursor clipping rectangle is the region of the 
window within which the cursor is visible, and it is specified by the last 
parameter (prclClip) passed to WinCreateCursor. If desired, you can 
set this rectangle to a subregion of the associated window. The user can 
freely move the cursor outside of the clipping rectangle; however, doing 
so will make the cursor invisible until it is brought back within the clip¬ 
ping rectangle. 

The example program assigns a value of NULL to the clipping rec¬ 
tangle parameter. This value causes WinCreateCursor to set the clip¬ 
ping region to the current dimensions of the entire window. Note, 
however, that if the window size is enlarged, the clipping rectangle 
remains the same, and thus becomes a subregion of the newly sized 
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window. If the user subsequently moves the cursor into the new area of 
the window, it will inexplicably disappear. 

The solution to both problems is for the WMSIZE routine to com¬ 
pletely destroy the existing cursor and then recreate the cursor, specify¬ 
ing the new cursor location and a clipping region that is the size of the 
current window (by passing NULL as the clipping rectangle 
parameter). The code required to perform these steps is listed in Figure 
5.9; this code is added to the Size function of the example program, 
which processes the WM SIZE message. 

Note, however, that before destroying and recreating the cursor, the 
program calls the Presentation Manager function WinQueryFocus (Fig¬ 
ure 5.10) to determine whether the client window currently has the 
focus. WinQueryFocus returns the handle of the current focus window. 
The program destroys and recreates the cursor only if this handle 
matches the handle of the client window, hwnd; otherwise, there is no 
cursor associated with the client window (the cursor will be properly 


/*** if client has focus, must RE-CREATE the cursor for new size. ************/ 

if (hwnd == WinQueryFocus /* Does client have focus? */ 

(HWND_DESKTOP, /* Must give desktop handle. */ 

FALSE)) /* Do not lock window. */ 

/*** Destroy existing cursor. *******************************************/ 
WinDestroyCursor (hwnd); 


/*** create new cursor. *************************************************/ 
WinCreateCursor /* Create a new cursor. */ 

(hwnd, /* Client window handle. */ 

(Cursored - FirstCol) * xChar, /* x position of cursor. */ 
yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 
0, /* x size of cursor: nominal border. */ 

yCharTot, /* y size of cursor. */ 

CURSOR_SOLID | /* Solid cursor. */ 

CURSOR_FLASH, /* Flashing cursor. */ 

NULL); /* Clipping rectangle: entire window.*/ 

/*** Display the cursor. ************************************************/ 
WinShowCursor 

(hwnd, /* Client window handle. */ 

TRUE); /* Show it! */ 

} 


• Figure 5.9: 

The routine in the function Size for recreating the cursor 
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recreated through the SetFocus function when the client window 
regains the focus). 

The routine in Figure 5.7 recalculates the cursor coordinates from the 
appropriate global program variables (CursorCol, xChar, and others), 
using the same expressions employed by the SetFocus function listed in 
Figure 5.2 and described previously in the chapter. In fact, all the 
parameters are the same as those passed by the function SetFocus; 
however, the effect of passing the value NULL for the clipping rectangle 
is to set this region to the new size of the client window, as desired. 


WinQueryFocus 


Purpose: 


Obtains the handle of the focus window. 

Prototype: 


| HWND APIENTRY WinQueryFocus 

(HWND hwndDesktop, 

The handle of the desktop window; 
you must assign the value 
HWND_DESKTOP. 

BOOL fLock); 

Lock indicator: if TRUE, the function 
will lock the window (a locked 
window cannot be destroyed); if 

FALSE, the window will not be locked. 

Return Value: 


The handle of the focus window, or NULL if there is no focus 

window. 



• Figure 5.10: 

The WinQueryFocus Presentation Manager function 


• MOVING THE CURSOR 

The two previous sections have shown how to create the cursor and 
how to maintain the cursor in proximity with its associated character in 
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the window. This section describes two situations in the current version 
of the example program in which the cursor is moved to another char¬ 
acter (as you will see, moving the cursor to another associated character 
does not necessarily change the cursor position with respect to the win¬ 
dow). First, pressing an arrow key, or the Home or End key, directly 
repositions the cursor on another character. Second, the cursor is moved 
to another character when the window is scrolled using a scroll bar or 
the PgUp or PgDn key. (The window may also have to be scrolled when 
the cursor is moved beyond the visible section of the file with the arrow, 
Home, or End key.) Chapter 6 will describe the movement of the cursor 
that occurs when you enter or delete characters in the file. 


The Cursor-Movement Keys 

The current version of the example program uses the four arrow 
keys and the Home and End keys for directly moving the cursor (unlike 
the previous version, which used the arrow keys to scroll the window). 
As explained in Chapter 4, these keys are among those identified by vir¬ 
tual key codes (used primarily to label keystrokes that do not have an 
ASCII value). Remember that the previous version of the program 
processed messages for the arrow and Home/End keys by passing 
these messages directly to the appropriate scroll bar control window 
(which then sent scrolling messages back to the client window). In the 
current version, however, the client window procedure processes these 
messages itself, without passing them through the scroll bar window 
procedures. (Note that the term client window procedure is used in a 
general sense to include not only the registered function, WndProc, but 
also all functions, such as Character and VirtKey, called by WndProc.) 

In the current version of the program, all virtual keys (such as the 
cursor-movement keystrokes) are processed in the function VirtKey. 
VirtKey is called by the client window procedure when it receives a 
WM_CHAR message for a virtual key. The manner in which a virtual 
key is recognized and the macro used to extract the codes for virtual keys 
will be explained in Chapter 6, which describes the complete keyboard 
interface. 
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The Arrow Keys 

The routine for processing the arrow keys is listed in Figure 5.11 
(this routine is part of the function VirtKey). Each of these keys is used 
to move the cursor one row or column in the corresponding direction. 

If the key is a t key (the VK_UP case), the program first tests whether 
the cursor is currently at the top line of the window. If the cursor is at 
the top of the window, the program needs to scroll the window up one 
row. Note that scrolling the window one row up is exactly the same task 
that is performed by the window procedure whenever it receives the 
WM_VSCROLL message, with an SBJLINEUP code. Therefore, rather 
than duplicating the scrolling routine within the function VirtKey (or 
sequestering this routine away in yet another subroutine), the program 
simply sends the appropriate message to itself. The program sends this mes¬ 
sage by calling the WinSendMsg Presentation Manager function (Fig¬ 
ure 4.8), specifying hwnd (the client window's own handle) as the 
target window. The message identifier is WM_VSCROLL, and the high- 
order word of nip2 is set to SB_LINEUP. Accordingly, when the system 
sends this message, control passes to the routine for scrolling up one 
row, which is within the VScroll function (to be described later in the 
chapter). 

This is the first of many examples of the client window procedure 
sending a message to itself, an important technique that deserves a 
small digression. Note that the WinSendMsg function causes the sys¬ 
tem to directly invoke the client window procedure (the message is not 
placed in the message queue). Therefore, if a window procedure directs 
a message to itself, the system generates a recursive call to the window 
procedure (a recursive call refers to a body of code reentering itself as a 
subroutine). When this recursive call completes, control returns to the 
original invocation of the window procedure. Recursive calls can also 
occur in other situations; for example, a call to WinDefWindowProc 
(Figure 2.17) may result in another message being sent back to the client 
window. In general, therefore, you must write all window procedure 
code with the possibility of recursive calls in mind. Accordingly, tem¬ 
porary variables that must be duplicated for each invocation of the pro¬ 
cedure should be declared as automatic variables. (Automatic variables 
are those declared within the scope of a function, not using the static 
keyword; these variables are placed within the procedure stack frame, 
which is distinct for each recursive call of the function. An automatic 
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/*** process up 
case VK_UP 

/*** If cursor at top of window, scroll up. ************************/ 
if (CursorLine == TopLine) 

{ _ 

WinSendMsg /* Scroll window one line up. */ 

(hwnd, 

WM_VSCROLL, 

OL, 

MPFR0M2 SHORT (0,SB_LINEUP)) ; 
return TRUE; 

} 

/*** if cursor NOT at top, simply adjust ’CursorLine 1 . *************/ 
else ' 

—CursorLine; 
break; 

/*** Process down-arrow key. ********************************************/ 

case VK_DOWN: ' 

/*** If cursor at end of file, simply return. **********************/ 

if (CursorLine == LastLine) 
return TRUE; 

/•*** If cursor is in bottom line of window, scroll down. ***********/ 
else if (CursorLine == TopLine + yWin / yCharTot - 1) 

WinSendMsg 
(.hwnd, 

WM_V S CRO LL, 

OL, 

MPFR0M2 SHORT (0,SB_LINEDOWN)) ; 
return TRUE; 

} t 

/*** Otherwise, simply adjust ’CursorLine’. ************************/ 
else 

-f-+CursorLine ; 
break; 

/*** Process left-arrow key. ********************************************/ 

case VK_LEFT: / 

/*** If cursor is at left of window, scroll left. ******************/ 
if (CursorCol == FirstCol) 

( 

WinSendMsg 

(hwnd, 

WM_HS CROLL, 

OL, 

MPFR0M2 SHORT (0,SB_LINELEFT)) ; 
return TRUE; 

} _ 

/*** Otherwise, simple adjust ’CursorCol’. *************************/ 

else 




Figure 5.11: 

The routine for processing arrow keys 
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® Figure 5.11: 

The routine for processing arrow keys (continued) 


variable can also be located at the SI or DI machine register; separate 
values are maintained for these registers for each function invocation.) 
For example, a local flag such as Update, used by the function VirtKey, 
should be an automatic variable. In contrast, variables that are to be 
shared by all invocations of a function should be declared as static, or 
declared outside of the function scope (external variables, required 
when more than one function must use the variable). For example, 
CursorLine is declared as an external variable so that it can be shared 
directly by any invocation of any function. 

If the cursor is not within the top line of the window, the routine for 
the VK_UP case simply decrements CursorLine and issues a break 
statement. When this routine—or any of the other routines that handle 
the arrow or Home/End keys—issues a break statement, control trans¬ 
fers to a call to WinCreateCursor, listed in Figure 5.12. Note that this 
function call passes a style value of CURSOR_SETPOS (as the sixth 
parameter, fs); this value causes the function to reposition an existing 
cursor rather than create a new cursor. When you specify CUR- 
SOR_SETPOS, the function ignores any other style values that you may 
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/*** Update cursor position for all cases above that altered 'CursorLine' or 
CUP SOrCol ^ o ~J^ ~ A ‘Jc A 1 ~ A & & & & & & & & A & ~ Jc & 


WinCreateCursor /* Set position of cursor, 

(hwnd, /* client window handle. 

(CursorCol - FirstCol) * xChar, /* x position of cursor. 

yWm - (CursorLine - TopLine + 1) * yCharTot, /* y position. 

/* x size of cursor: n/a. 

0/ /* y size of cursor: n/a. 

CURSOR_SET p °s, /* option to set position only. 

NULL ' ; /* Clipping rectangle: n/a 


Figure 5.12: 

The call to WinCreateCursor for updating the cursor position 


*/ 

V 

V 

V 

V 

V 

V 

V 


unwittingly include, as well as the cursor size dimensions (the fourth 
and fifth parameters, cx and cy). When the program calls WinCreate¬ 
Cursor, the new value of CursorLine causes the system to move the 
cursor up one line. 

The routine for the down-arrow case (VK_DOWN) performs a 
similar task, scrolling the window one line down if the cursor is on the 
bottom line in the window, or simply decrementing CursorLine and is¬ 
suing a break statement if the cursor is above the last line. In the same 
manner as the up-arrow case, the break statement passes control to the 
call to WinCreateCursor, listed in Figure 5.12, which serves to move 
the cursor one line down. Note, however, that the down-arrow routine 
returns immediately if the cursor is already on the last line in the file 
(LastLine, which might not be the bottom of the window). 

The routines for the <— and —> keys (VKLEFT and VK_RIGHT) work 
in a manner exactly analogous to the routine for the up-arrow and 
down-arrow cases. 


The Home and End Keys 

The Home and End keys serve to move the cursor to the begin¬ 
ning or the end of the current line. The branches of the switch statement 
that handle these keys are listed in Figure 5.13. 

The routine that processes the Home key (VK HOME) simply sets 
CursorCol to 0 and branches to the call to WinCreateCursor (by is¬ 
suing a break statement) to move the cursor to the first column. Note, 
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/*** Process Home key. **************************************************/ 
case VK_HOME: 

f k-k-k scroll if beginnings of lines not visible. ********************/ 
if (FirstCol != 0) 

{ 


WinSendMsg 


} 


/* Send scroll to absolute position */ 
/* message to self. */ 

(hwnd, 

WM_HSCROLL, 

0L, 

MPFR0M2SHORT (0,SB_SLIDERPOSITION)); 


CursorCol = 0; 
break; 

/*** Process End key. ***************************************************/ 

case VK_END: 

/*** Set temporary cursor position to end of line. *****************/ 
NewCursorCol = (int)GetLineLength (CursorLine); 

/*** Clear update flag. ********************************************/ 
Update = 0; 

/*** End of line to right of portion visible in window. ************/ 
if (NewCursorCol > FirstCol + xWin / xChar - 1) 

{ 

NewFirstCol = NewCursorCol - xWin / xChar + 1; 

Update = 1; 

/*** End of line to left of portion visible in window. **************/ 
else if (NewCursorCol < FirstCol) 

{ 

NewFirstCol = NewCursorCol; 

Update = 1; 

/*** Scroll window if end of line not visible. *********************/ 
if (Update) 

WinSendMsg 
(hwnd, 

WM_HSCROLL, 

0L, 

MPFROM2 SHORT (NewFirstCol, 

S B_S LIDERPOSITION) ) ; 

/■*** Set permanent cursor column position. *************************/ 
CursorCol = NewCursorCol; 
break; 


Figure 5.13: 

The routines for processing the Home and End keys 
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/*** process Page Up key. ***********************************************/ 
case VK_PAGEUP: 

WinSendMsg /* Send scroll page up message to self. */ 

(hwnd, 

WM_VSCROLL, 

0L, 

MPFROM2 SHORT (0,SB_PAGEUP)) ; 
return TRUE; 

/*** Process Page Down key. *********************************************/ 
case VK_PAGEDOWN: 

WinSendMsg /* Send scroll page down message to self. */ 

(hwnd, 

WM_VSCROLL, 

0L, 

MPFROM2SHORT (0,SB_PAGEDOWN)); 
return TRUE; 


® Figure 5.13: 

The routines for processing the Home and End keys (continued) 

however, that in keeping with the philosophy that the cursor position 
should always be visible within the window, the routine scrolls the win¬ 
dow to the far left if the new cursor position would fall outside the cur¬ 
rently visible range of the file lines (in other words, if FirstCol is not 
equal to 0). As in the arrow-key routines, the window procedure easily 
generates the appropriate scrolling action by sending a WM HSCROLL 
message to itself, via the WinSendMsg function. Note, however, that 
the accompanying action code is set to SB_SLIDERPOSITION (in the 
high-order word of mp2), which specifies an absolute position (0, 
placed in the low-order word of mp2); the resulting message is the same 
as that generated when the user moves the horizontal scroll bar slider to 
the beginning of its range. 

The Home-key routine concludes with a break statement, which pas¬ 
ses control to the WinCreateCursor function call (listed in Figure 5.12) 
to move the cursor to its new position. 

The logic for the End key is similar to that for the Home key, but is slight¬ 
ly more complex because the new cursor position (at the end of the dis¬ 
played line) may be either to the right or to the left of the block of file data 
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currently displayed in the window. The routine tests for both of these 
conditions; if either condition is true, it performs the following actions: 

® It calculates a new value for FirstCol that would bring the cursor 
just into the visible portion of the window (if the cursor falls to 
the right of the window, it is moved to the right edge within the 
window; if it falls to the left, it is moved into the window at the 
left edge). Note, however, that the new value is not assigned to 
FirstCol, but is held in the temporary variable NewFirstCol (the 
reason will be explained later). 

© It sets the Update flag, indicating that the window must be 
scrolled either right or left. 

If the Update flag is set, the program then scrolls the window 
horizontally by sending a message to itself, in the same manner as the 
Home-key routine, except that the absolute position is specified as 
NewFirstCol. Note that you cannot assign the value held in NewFirst¬ 
Col directly to the global variable FirstCol before calling the scrolling 
routine, because this routine calculates the new value of FirstCol based 
upon the former value of the variable (which must therefore be left intact). 

Finally, whether or not the window requires scrolling, the End-key 
routine assigns the appropriate new value to CursorCol to place the 
cursor at the end of the line (this value was obtained from the buffer 
module function GetLineLength and was stored in the temporary vari¬ 
able NewCursorCol). The routine then issues a break statement so that 
control will pass to the call to WinCreateCursor that moves the cursor. 


Moving the Cursor When Scrolling 

As in the previous version of the example program, the scrolling 
messages (WM_HSCROLL and WMJVSCROLL) are handled by the H~ 
Scroll and VScroll functions. The current versions of these functions, 
however, must contain additional logic to maintain the correct position 
of the cursor within the window. Before describing this logic, however, 
this section summarizes the various methods by which scrolling mes¬ 
sages are generated in the example program. 
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Generation of Scrolling Messages 

In the current version of the example program, the messages 
WM_VSCROLL and WM HSCROLL are sent to the client window 
under the following circumstances: 

® As seen in the previous section, scrolling messages are sent by 
the routines that process the cursor-movement keys (that is, the 
arrow. Home, and End keys) whenever these keys move the cur¬ 
sor to a point that is outside the section of the file currently dis¬ 
played within the window. 

• In the same manner as the previous version of the program, the 
scroll bars send scrolling messages whenever they receive 
relevant mouse input. 

• The VirtKey function sends the WM VSCROLL message in 
response to the PgUp or PgDn key. 


/*** Process Page Up key. ***********************************************/ 
case VK_PAGEUP: 

WinSendMsg /* Send scroll page up message to self. */ 

(hwnd, 

WM_V S CRO LL, 

OL, 

MPFROM2SHORT (0,SB_PAGEUP)); 
return TRUE; 

/*** process Page Down key. *********************************************/ 
case VK_PAGEDOWN: 

WinSendMsg /* Send scroll page down message to self. */ 

(hwnd, 

WM_VS CRO LL, 

OL, 

MPFROM2 SHORT (0,SB_PAGEDOWN) ) ; 
return TRUE; 


® Figure 5.14: 

The routine for processing the PgUp and PgDn keys 
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The routine for processing the PgUp and PgDn keys (which is con¬ 
tained in the routine VirtKey) is listed in Figure 5.14. In these two 
branches of the switch statement, the window procedure simply sends 
itself a WM_VSCROLL message, accompanied by either the 
SB_PAGEUP or SBJPAGEDOWN action code. 

Maintaining the Cursor When Scrolling 

As you have seen, the HScroll and VScroll functions scroll the 
window in the appropriate direction by calling the WinScrollWindow 
function. WinScrollWindow, however, is slightly overzealous and 
scrolls not only the window data, but also the cursor image. The ex¬ 
ample program is designed to maintain the cursor in the same relative 
position with respect to the window each time the window is scrolled 
(which causes a shift in the character associated with the cursor). There¬ 
fore, the HScroll and VScroll functions must contain instructions to 
place the cursor back in the same window position after the window is 
scrolled. (These routines also need to update the global variables 
CursorCol and CursorLine, which change each time the window 
is scrolled.) 

To maintain the cursor in the same relative position with respect to 
the window, HScroll performs the following tasks in addition to those 
performed in the previous version of this function: 

© Once the number of columns the window is to be scrolled 

(Delta) has been calculated, the routine uses this quantity to cal¬ 
culate the new value of CursorCol, as follows: 

CursorCol += Delta; 

Note that the same quantity (Delta) is added to both FirstCol and 
CursorCol, thus keeping the cursor in its same horizontal posi¬ 
tion with respect to the window. 

© Before scrolling the window, the routine calls the function Win- 
ShowCursor (Figure 5.5), passing a value of FALSE as the 
second parameter to hide the cursor. Making the cursor invisible 
before scrolling prevents the unpleasant visual effect as the cur¬ 
sor scrolls away from the window edge and then is moved back 
to the edge when you repeatedly scroll the window by holding 
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down the arrow key (the cursor appears to hammer against the 
edge of the window). 

© At the end of the HScroll function, WinCreateCursor is called to 
restore the cursor to its appropriate window location. The func¬ 
tion call is the same as that listed in Figure 5.12. 

• Immediately before returning, HScroll calls WinShowCursor 
once again, this time passing TRUE as the second parameter to 
make the cursor reappear. 

The VScroll function performs these same additional tasks, except 
that it updates the variable CursorLine rather than CursorCol. 


• CONCLUSION 

A MAKE file for the current version of the example program is 
listed in Figure 6.22, and the definition file in Figure 6.23. Figure 6.24 
provides a complete program listing that contains all of the features dis¬ 
cussed in this chapter as well as in Chapter 6. 

The routines presented in this chapter have added a cursor to the ex¬ 
ample program. Since the cursor marks the current insertion point 
within the file, the next logical step is to allow you to begin inserting 
characters. Chapter 6 adds a complete keyboard interface to the ex¬ 
ample program, which permits you to enter new characters as well as 
delete existing characters. 
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he version of the Presentation Manager text editor pre¬ 
sented in this chapter finally allows you to edit the con¬ 
tents of the file. (You should not invest too much time 
changing the file, however, since you will not be able to 
save these changes until the version of the program given in Chapter 7!) 
You can type characters directly into the file at the insertion point 
marked by the cursor created in Chapter 5, and you can insert new lines 
by pressing the Enter key. You can also delete individual characters 
with the Del and Backspace keys, or delete entire lines by pressing F9. 
The program supports both overwrite and insert modes, and permits 
you to edit an existing file or start a new file. 

In this chapter, you will learn how to interpret keyboard messages 
sent to the client window; you will learn how to process normal charac¬ 
ter keys, as well as the keys identified by virtual codes (such as function 
or arrow keys); and you will learn how to manipulate the data struc¬ 
tures containing the file data in order to modify the contents of the file. 

The new features of the example program discussed in this chap¬ 
ter reside in the window procedure subroutines that process the 
WM_CHAR message, and in the buffer-management module. The 
character-handling routines now process most of the keyboard mes¬ 
sages, rather than simply ignoring the majority of keyboard input. 
These routines are supported by eight new functions in the buffer- 
management module for inserting and deleting characters and lines. 
The discussions in this chapter focus on the routines of the window pro¬ 
cedure, which illustrate techniques unique to the Presentation Manager. 
A lengthy discourse on the more conventional code within the buffer- 
management module would be a digression from the primary topic of 
this book; therefore, the chapter clearly illustrates the purpose of each 
of these functions when they are first encountered, but discusses only 
the most salient points of their implementation. 

The complete listing of the current version of the example program is 
given in Figure 6.24, at the end of the chapter. 



• THE WM_CHAR MESSAGE 

Whenever a key is either pressed or released, the Presentation 
Manager records the event by placing an entry in a single keyboard 
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buffer known as the system queue. This queue is large enough to store 
approximately 60 keyboard events, and thus allows you to type keys 
well ahead of the processing of these keys by the active application. The 
Presentation Manager dispenses with the entries in the system queue by 
sending WM_CHAR messages, one at time, to the window that current¬ 
ly owns the input focus. 

The system sends WM_CHAR messages by posting them to the mes¬ 
sage queue owned by the window with the focus (in contrast to high- 
priority messages sent by directly calling the window procedure). The 
Presentation Manager, however, does not post a WM_CHAR message 
until the window procedure has finished processing the previous WMJ2HAR 
message. (The system knows that the procedure has completed process¬ 
ing a message when the window thread calls the WinGetMsg function 
to obtain another message.) The system can post only one WM_CHAR 
message at a time because the processing of a given message may 
change the focus window at any time (for example, a window procedure 
could call WinSetFocus or WinSetActiveWindow to explicitly change 
the focus or the active window). If the Presentation Manager posted 
a second keyboard message to the focus window before the first mes¬ 
sage was processed, the second message could end up being sent to the 
wrong window. Note that if no window currently owns the focus, the 
WM_CHAR message is sent to the active window (the concept of the focus 
and active window was discussed in the section of Chapter 4 on Creating 
the Scroll Bars). 

Figure 6.1 describes the WM_CHAR message. As you can see from 
this description, a large amount of information is encoded in the two 
message parameters, mpl and mp2, that are passed to the window proce¬ 
dure. Fortunately, the system provides a macro, CHARMSG, that 
simplifies extracting specific values from these parameters. This macro 
works in conjunction with a specially defined structure (both the macro 
and the associated structure are defined in the PMWIN.H header file). The 
definition of the macro is somewhat complex; however, its use is simple. 
The following table lists the values you can extract with this macro: 

Macro Format Value Extracted 

from Parameters 

Hardware scan code 

Character code 


CHARMSG (&msg)->scancode 
CHARMSG (&msg)->chr 
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CHARMSG (&msg)->vkey Virtual-key code 

CHARMSG (&msg)->cRepeat Repeat count 

CHARMSG (&msg)->fs Keyboard control flags 

Note that msg is the name of the second parameter (the message iden¬ 
tifier) passed to the window procedure in the example program. If your 
program uses a different name for this parameter, substitute this name 
in the preceding expressions; otherwise, the expressions should be ex¬ 
actly as listed. 


WM CHAR 


Purpose: 

Sent by the system to the focus window (or active window, if 
there is no focus window) to notify it of a keyboard event 
(that is, a key pressed or released). 


Parameters: 

MPARAM mpl 

low-order 16 bits: Keyboard control flags; the individual 

flags can be extracted using the 
following identifiers: 


Identifier 
KC_CHAR 
KC_SC AN CODE 
KC_VIRTUALKEY 
KCJKEYUP 


KC_PREVDOWN 


Meaning If Flag Is Set 

Character code is valid 
Scan code is valid 
Virtual-key code is valid 

The key was released 
(otherwise, the key was 
pressed) 

The key was previously 
down (otherwise, it 
was previously up) 


• Figure 6.1: 

The WM_CHAR Presentation Manager message 
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KC_DEADKEY 

The key is a dead key 
(a keystroke that 
should not advance the 


cursor, such as an 
umlaut) 

KC_COMPOSITE 

Key code was obtained 
by combining current 
key with previous 
dead key 

KCJNVALIDCOMP 

Current key does not 
form a valid 
combination with 
previous dead key 

KC_LONEKEY 

The key was pressed 
and released without 
other keys being 
pressed between the 
time the key went 
down and up 

kc_shift 

The Shift key was 
down when the key 
was pressed or released 

KC_ALT 

The Alt key was down 
when the key was 
pressed or released 

KC_CTRL 

The Ctrl key was down 
when the key was 
pressed or released 

next 8 bits: Repeat count. 


high-order 8 bits: Hardware scan code. 

| MPARAM mp2 


low-order 16 bits: Character code (if KC_CHAR flag is 

set); typically an ASCII code. 

| high-order 16 bits: Virtual-key code (if KC_VIRTUALKEY 

flag is set); see Table 6.1 for a list of 
some of these codes. 

Return Value: 


Return TRUE if the message was processed, or FALSE if the 

message was ignored. 



® Figure 6.1: 

The WM_CHAR Presentation Manager message (continued) 
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The Scan Code 

The scan code is a number identifying the specific key on the key¬ 
board. The meaning of a given scan code depends upon the particular 
keyboard hardware that is installed; therefore, you should not use these 
codes if your program is to remain device-independent. You can find 
the meanings of the scan codes for a given machine in the appropriate 
hardware technical reference manual. (Many MS-DOS applications, 
which are typically targeted to a narrow range of machine models, rely 
upon the hardware scan codes.) 


The Character Code 

For all keystrokes that represent characters—letters, numbers, or 
symbols—the Presentation Manager translates the scan code into a 
hardware-independent character code. This code is typically the stand¬ 
ard ASCII value of the key, although the system may be configured to 
use EBCDIC values or extended codes for foreign keyboards. The 
Presentation Manager derives this code based upon the following data: 

• The hardware scan code indicating the specific key pressed or 
released 

• The current state of the shift keys—Alt, Ctrl, and Shift 

® The currently installed translation table, which maps scan- 
code/ shift-state combinations into the appropriate character 
codes for the specific country and computing environment 


The Virtual-Key Code 

The Presentation Manager introduces a new class of keystroke iden¬ 
tifiers known as virtual codes. A virtual code is a hardware-independent 
value used to identify keys that do not have character values, such as 
function keys, arrow keys, the Ins key, and so on. (Note that certain keys 
may have both a character code and a virtual code, such as the Enter 
key.) Table 6.1 lists the virtual code identifiers provided by the system 
header files. Unlike scan codes, the virtual code for a key with a given 
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label (such as "FI" or "Home") does not depend upon the specific key¬ 
board hardware. Therefore, a program that uses these keys will remain 
device-independent. Note, however, that the codes in Table 6.1 marked 
with an * are not generated by all keyboards; if you use these codes in 
your application, you should provide alternative keystrokes. 

In the same manner as the character codes, the Presentation Manager 
derives the virtual code from the hardware scan code using the current¬ 
ly installed translation table. In general, however, the shift state does 
not affect the virtual code. 


The Repeat Count 

Typically, the keyboard hardware automatically sends a series of 
repeated signals when you hold a key down longer than a certain 
threshold period. As mentioned, the Presentation Manager posts 
WM_CHAR messages one at a time; an application, however, may not be 
fast enough to process the keystrokes at the same rate they are generated. 
Therefore, instead of posting all repeated keystrokes in the focus window's 
queue, the Presentation Manager posts a single message that contains a 
count of the total number of repetitions that occurred since the last key 
message was extracted from the queue. This procedure, known as coalesc¬ 
ing repeated keystrokes, helps prevent an application from receiving key¬ 
board messages faster than it can process them. 

If your program needs to handle every keystroke, it can execute its 
processing routine the number of times indicated by the repeat count 
(for example, by placing this routine within a loop and using the repeat 
value as the loop counter). The example program, however, simply ig¬ 
nores the repeat count, since it may be unable to process keys rapidly 
enough to handle all repeated keystrokes (especially if the keyboard 
repeat rate is set at a high value). For example, if you scroll the window 
toward the end of the file by keeping the 1 key depressed, the program 
must scroll the entire screen contents with each keystroke processed, 
which is a time-consuming procedure. If the program attempted to process 
every repeated keystroke, keystrokes would most likely accumulate in the 
system queue; as a consequence, when you release the key, many messages 
would be left in the queue and the window would continue to scroll long 
after the I key was released. Such distressing overscrolling can be 
eliminated by simply disregarding the repeat count. 
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• Table 6.1: The Virtual-Key Codes 


Identifier 

Value (hex) 

Notes 

VK_BREAK 

0x04 

* 

VK_BACKSPACE 

0x05 

Backspace 

VK_TAB 

0x06 

Tab 

VK_BACKTAB 

0x07 

Shift-Tab 

VKJMEWLINE 

0x08 

Enter 

VK_SHIFT 

0x09 

Shift 

VK„CTRL 

OxOA 

Ctrl 

VKALT 

OxOB 

Alt (down only) 

VK_ALTGRAF 

OxOC 

* 

VK_PAUSE 

OxOD 

* 

VK_CAPSLOCK 

OxOE 

Caps Lock 

VK_ESC 

OxOF 

Esc 

VK_SPACE 

0x10 

Spacebar 

VK_PAGEUP 

0x11 

PgUp 

VK_PAGEDOWN 

0x12 

PgDn 

VK_END 

0x13 

End 

VK_HOME 

0x14 

Home 

VK_LEFT 

0x15 

Left-arrow 

VKJUP 

0x16 

Up-arrow 

VK_RIGHT 

0x17 

Right-arrow 

VK_DOWN 

0x18 

Down-arrow 

VK_PRINTSCRN 

0x19 

Shift-PrtSc 

VKJNSERT 

Oxl A 

Ins 

VK_DELETE 

OxlB 

Del 

VK_SCRLLOCK 

Oxl C 

Scroll Lock 

VKNUMLOCK 

Oxl D 

Num Lock 

VK_ENTER 

Oxl E 

* (not the normal 
Enter key) 
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@ Table 6.1: The Virtual-Key Codes (continued) 


Identifier 

Value (hex) 

Notes 

VK_SYSRQ 

OxlF 

* Sys Req 

VKJF1 

0x20 

FI 

VK_F2 

0x21 

F2 

VK_F3 

0x22 

F3 

VK_F4 

0x23 

F4 

VK_F5 

0x24 

F5 

VK__F6 

0x25 

F6 

VK_F7 

0x26 

F7 

VK_F8 

0x27 

F8 

VK_F9 

0x28 

F9 

VK_F10 

0x29 

F10 

VK_F11 

0x2A 

*F11 

VK_F12 

0x2B 

* F12 

VKJF13 

0x2C 

* F13 

VK_F14 

0x2D 

* FI 4 

VK_F15 

0x2E 

*F15 

VK_F16 

0x2F 

*F16 

VK_F17 

0x30 

* F17 

VK_F18 

0x31 

*F18 

VK_F19 

0x32 

*F19 

VK_F20 

0x33 

* F20 

VK_F21 

0x34 

*F21 

VK_F22 

0x35 

* F22 

VK_F23 

0x36 

* F23 

VK_F24 

0x37 

* F24 

VK_MENU 

VK_ALT 

Alt 

* Marks codes that are not generated by all keyboards 
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The Keyboard Control Flags 

Each keyboard message also includes a 16-bit value containing key¬ 
board control flags. The individual bits of this word serve as flags indicat¬ 
ing the state of the keyboard at the time the key was pressed or released. 
You can access the desired bit by using the appropriate constant as a bit 
mask; constants are provided in the PM WIN.H include file, and are listed 
in Figure 6.1. The binary value of each of these constants consists of all 
zeros, with a single 1 in the position of the appropriate bit of the flag word; 
you can therefore use the constant in conjunction with the & operator to 
test whether the given flag is set. For example, the sixth bit in the control 
flag word is set when the key has been released and is zero when the key 
has been pressed; accordingly, the constant KCJKEYUP has the value 
0x0040, and can be used as follows: 

if (CHARMSG (&msg)->fs & KCJKEYUP) 

/* then key was released; therefore ignore message*/ 
else 

/* then key was pressed; therefore process message*/ 

Figure 6.2 lists the WM_CHAR routine within the client window pro¬ 
cedure (WndProc) of the example program, which uses the keyboard 
flags to perform the initial processing of all keyboard messages. This 
routine first tests the KCJKEYUP bit of the control flags to determine 
whether the key was pressed or released. If the key was released, the 
window procedure immediately returns FAFSE, which indicates to the 
system that the key message was ignored (returning TRUE notifies the 
system that the key was processed). 

Next, the program tests the KC_CHAR bit of the control flags. If this 
flag is set, then the keyboard message contains a valid character code 
and control passes to the function Character, which processes all char¬ 
acter keys and is described in the next section. If the message does not 
contain a valid character code, then the routine goes on to test the 
KC_VIRTUAEKEY flag. If this flag is set, then the message has a valid 
virtual code, and the program calls the VirtKey function to process 
the virtual key; this function is described later in the chapter. Finally, if 
neither flag is set, the window procedure returns immediately; theoreti¬ 
cally, this case should never occur. 
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case WM_CHAR: /* Message sent when keyboard key is received. */ 

/*** Don't process a key-released message. *************************/ 
if (CHARMSG (&msg)->fs & KC_KEYUP) 
return FALSE; 

/*** Process character key. ****************************************/ 
else if (CHARMSG (&msg)->fs & KC_CHAR) 

return Character (hwnd, msg, mpl, mp2); 

/*** Process virtual key. ******************************************/ 
else if (CHARMSG (&msg)->fs & KC_VIRTUALKEY) 
return VirtKey (hwnd, msg, mpl, mp2); 

/*** Don't process invalid key. ************************************/ 
else /* Invalid key; neither virtual nor character. */ 

return FALSE; 


• Figure 6.2: 

The initial processing of the WM_CHAR message 


• THE CHARACTER KEYS 

All WM_CHAR messages with valid character codes are pro¬ 
cessed by the function Character in the example program. This function 
contains separate routines for each of the following keys: 

© Backspace key 

• Tab key 

• Enter key 

• All remaining character keys 

Processing any of these keys results in modifying the contents of the 
file buffer—adding, deleting, or changing characters. In the previous 
version of the example program, all file lines were stored in separately 
allocated memory blocks within the heap. As illustrated in Figure 3.9, 
the address of each line within the heap is stored in line-number order 
within the array LineTable, permitting rapid random access to any file 
line. The present version of the program stores all lines within the heap 
except the line that is currently being modified. While a line is being 
modified it is temporarily stored in a local array, LineBuffer; the size of 
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this buffer (LINEBUFSIZ, which currently equals 255 but could easily 
be modified) represents the greatest line length that can be managed by 
the program. The new overall data structure is illustrated in Figure 6.3. 

Lines are not modified directly within the heap, because modifica¬ 
tion usually results in a change in the line length, and the memory 
blocks within the heap are the exact sizes of the lines they contain. 
When you have completed altering a given line, the characters in that 
line are copied into a newly allocated block within the heap, which has 
a size that matches the new length of the line. File lines are modified 
through the following sequence of steps: 

1. When the program begins, the cursor is placed in file line 0 and 
the data for this line is contained in LineBuffer. Accordingly, 
LineTable [0] holds the address of LineBuffer rather than that of 
a block within the heap. 

2. Any character keys you enter cause the modification of the con¬ 
tents of LineBuffer. 

3= You can freely move the cursor throughout the file. If, however, 
you enter a character key when the cursor is on a new line, then 
the program executes a sequence of steps to store line 0 back 
into the heap and place the contents of the new line into Line- 
Buffer. This sequence of steps is repeated each time you enter a 
character key into a new line. 

The number of the line that was most recently modified is stored in 
the variable LastCursorLine. Accordingly, the function Character first 
compares LastCursorLine with CursorLine, the line currently contain¬ 
ing the cursor. If these values are unequal, then the user has moved the 
cursor to a new line and is in the process of modifying this line by enter¬ 
ing a character key. Therefore, the program performs the sequence of 
steps necessary to store the former line back into the heap and to copy 
the new line into LineBuffer. The code that makes this test and per¬ 
forms these steps is as follows: 

if (LastCursorLine != CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 
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• Figure 63: 

The data structure used to store and modify the file lines 
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LastCursorLine = CursorLine; 

} 

The function ReleaseTempBuf, located in the buffer-management 
module of the example program, is listed in Figure 6.4. This function is 
passed the number of the line that was most recently modified (Last- 
CursorLine), and performs the following steps: 

1. It allocates a block within the heap just large enough to hold the 
modified line currently contained in LineBuffer. 


void ReleaseTempBuf 

(int Line) /* Number of line held in 'LineBuffer'. */ 

/* 

This function: 

o Allocates a new block of memory just large enough to hold the string in 
the 'LineBuffer' 

o Copies the string into the new block 
o Adjusts the address in 'LineTable' 

V 

{ 

NPCH HeapOffset; /* Offset of block within heap. */ 

/*** Allocate a block to hold current contents of 'LineBuffer'. **************/ 
HeapOffset = WinAllocMem 
(HHeap, 

LineTable [Line].LineLength); 
if (HeapOffset == NULL) 

{ 

sprintf (Message,"out of heap memory; line %d",_LINE_); 

ErrorQuit (Message); 

) 

/*** Copy characters from 'LineBuffer' into new block in heap. ***************/ 


movedata /* Intersegment block copy. */ 

(Lineselector, /* Source: selector of line buffer. */ 

LineOffset, /* Source: offset of line buffer. */ 

HeapSelector, /* Target: selector of heap. */ 

(unsigned)HeapOffset, /* Target: offset of new block. */ 

LineTable [Line].LineLength); /* Bytes to copy. */ 


/*** Adjust address in 'LineTable' to point to new block. ********************/ 
LineTable [Line].LineAddress = MAKEP (HeapSelector, HeapOffset); 

} /* end ReleaseTempBuf */ 


® Figure 6.4: 

The function ReleaseTempBuf of the example program 
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2. It copies the contents of modified line from LineBuffer into the 
new block in the heap. 

3. It adjusts the appropriate entry in LineTable to point to the new 
heap block instead of to LineBuffer. 

Note that the data are copied by calling the C function movedata, which 
generates an efficient intersegment block-copy operation. 

The function GetTempBuf (listed in Figure 6.5) is called next; this 
function is also in the buffer-management module. GetTempBuf is 


void GetTempBuf /* Places specified line into 'LineBuffer 1 . */ 

(int Line) /* Number of line. */ 

/* 

This function: 

o Copies the string in the specified line into 'LineBuffer' 
o Frees the block formerly holding the string 
o Adjusts the address in 'LineTable' 

V 

{ 

/*** Copy string into 'LineBuffer'. ******************************************/ 
movedata /* Intersegment block copy.*/ 


(SELECTOROF (LineTable[Line].LineAddress), 

/* 

Source 

segment. 

V 

OFFSETOF (LineTable[Line].LineAddress), 

/* 

Source 

offset. 

V 

LineSelector, 

/* 

Target 

segment. 

V 

LineOffset, 

/* 

Target 

offset. 

V 

LineTable [Line].LineLength); 

/* 

Bytes to copy. 

*/ 


/*** Release block formerly holding line. ************************************/ 
if (WinFreeMem 

(HHeap, /* Handle of heap from 'WinCreateHeap'. */ 

(BYTE NEAR *)OFFSETOF (LineTable [Line].LineAddress), /* Offset. */ 

LineTable [Line].LineLength) /* Length of block to free. */ 

!= NULL) 

{ 

sprintf (Message,"managing heap; line %d",_LINE_); 

ErrorQuit (Message); 

} 

/*** place new address into 'LineTable'. *************************************/ 
LineTable [Line].LineAddress = MAKEP (LineSelector,LineOffset); 

} /* end GetTempBuf */ 


® Figure 65: 

The function GetTempBuf of the example program 
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passed the number of the new line that is about to be modified (Cursor- 
Line), and performs the following steps: 

1. It copies the line that is about to be modified from the heap into 
LineBuffer. 

2. It releases the block formerly used to hold this line within the 
heap. 

3. It adjusts the appropriate entry in LineTable to point to Line- 
Buffer rather than to the heap block. 

The modifications to the file data structure made by the calls to 
ReleaseTempBuf and GetTempBuf are illustrated in Figure 6.6. Once 
the former line has been safely stored away in the heap, and the current 
line is ready to modify in LineBuffer, the program updates LastCursor- 
Line to contain the current cursor line. 

At this point, whether or not the file buffer needed to be adjusted, the 
function Character branches to the appropriate routine to process the spe¬ 
cific character key. Each of these routines is discussed in the remainder of 
this section, in the order of increasing complexity. 


Normal Character Keys 

This section discusses the processing of all character keys that do 
not have special control significance in the example program (that is, all 
keystrokes that generate a valid character code except Backspace, Tab, 
and Enter). These keys are inserted directly into the data buffer; the 
routine that processes them is listed in Figure 6.7. This routine 
demonstrates the four basic steps required to perform an editing opera¬ 
tion on the file. Several of the other routines in the program follow these 
same general procedures, which can be summarized as follows: 

1. Call the appropriate function in the buffer-management module 
to effect the internal change to the file data structure. 

2. Signal the user if the maximum line length or maximum heap 
size has been reached and the editing function cannot be 
performed. 
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• Figure 6.6: 

The changes made by ReleaseTempBuf and GetTempBuf to the file data structure 
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3. Invalidate the region of the window that must be updated to 
reflect the change just made to the file buffer, and call Win- 
UpdateWindow to expedite the repainting of the window. 

4. Update the position of the cursor by sending the appropriate 
scrolling message back to the window procedure. 

The routine first inserts the character into the file buffer by calling the 
function InsertChar (located in the buffer-management module and 


/*** Process all remaining character keys. ***********************************/ 

/*** insert key into file buffer. ********************************************/ 
if (!InsertChar 

(CursorLine, 

CHARMSG(&msg)->chr, 

CursorCol, 

Insert)) 

{ 

/*** Beep if insertion failed (max buffer length 
WinAlarm (HWND_DESKTOP, WA_ERROR); 
return TRUE; 

} 

/*** invalidate window from cursor position to end of 

Rect.xLeft = (CursorCol - FirstCol) * xChar; 

Rect.xRight = min ((GetLineLength (CursorLine) - 
Rect.yBottom = yWin - (CursorLine - TopLine + 1) 

Rect.yTop = Rect.yBottom + yCharTot; 


WinlrivalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* Don't include descendants w/ WS_CLIPCHILDREN*/ 

WinUpdateWindow (hwnd); /* Force updating of client window. */ 

/*** Move the cursor right one column. ***************************************/ 

WinSendMsg /* Send right-key message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character message. */ 

MPFR0M2SHORT (KC_VIRTUALKEY,1), /* mpl. */ 

MPFR0M2SHORT (0, VK_RIGHT)) ; /* mp2. */ 


exceeded). *************/ 

line (or window). ******/ 

FirstCol) * xChar, xWin); 
* yCharTot; 


return TRUE; 


• Figure 6.7; 

The routine for processing normal character keys 
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listed in Figure 6.8). InsertChar is passed the character to insert 
(CHARMSG(&MSG)->chr), the row and column position of the inser¬ 
tion point within the file (CursorLine and CursorCol), and a flag con¬ 
taining the current insert mode (Insert). Note that the program is in the 
insert mode when the global variable Insert is set to 1, and it is in 
the overwrite mode when this variable is set to 0. Insert is initialized to 
1, placing the program initially in the insert mode, and it is toggled in 
response to the Ins key (the processing of this key is explained in the 
section on the virtual keys). 

InsertChar returns TRUE if the character was successfully inserted, 
and FALSE if inserting the character would cause the maximum line 
length to be exceeded. The character is written into LineBuffer (which 
contains the file line currently being modified) at the specified column 
position, which corresponds to the current position of the cursor in the 
window. If the insert mode is active, any existing characters at the inser¬ 
tion point or to the right of this point (that is, at larger offsets) are 
moved one byte toward the end of the buffer. If the overwrite mode is 
active, the new character is simply written over any existing character. 
If the specified insertion point is beyond the current end of the line, the 
function pads the buffer with space characters between the end of 
the line and the new character. In all cases, the line is terminated with a 
newline character ('\n') followed by a null ('\0'), and the line length in 
LineTable is adjusted to the new length. Note that buffer characters are 


int InsertChar / 

(SHORT Line, / 

USHORT Character, / 

SHORT Column, / 

int Insert) / 

{ 


unsigned char LineLength; 


Inserts character into ’LineBuffer’. 
Number of line for insertion. 
Character to insert. 

Column position of character. 

Flag indicating overwrite mode. 


/*** Obtain the length of the line. ******************************************/ 
LineLength - LineTable [Line].LineLength; 


/*** if Une would exceed maximum line length, return without inserting. *****/ 
if (Column > LINEBUFSIZ - 3 || LineLength >= LINEBUFSIZ && Insert) 

return FALSE; 


/*** jf column is at end of line (common case), use fast routine to insert. **/ 
else if (Column == LineLength - 2) 


® Figure 6.8: 

The function InsertChar of the example program 





/*** Copy '\n' and ’\0' to new position. ********************************/ 
LineBuffer [Column + 2] = LineBuffer [Column + 1]; 

LineBuffer [Column + 1] = LineBuffer [Column]; 

/*** Write the character. ***********************************************/ 
LineBuffer [Column] = (char)Character; 

/*** Adjust line length. ************************************************/ 
++LineTable [Line].LineLength; 
return TRUE; 

} 

/*** If column is BEYOND end of line, must pad line with spaces. *************/ 

else if (Column > LineLength - 2) 

/*** Copy 1 \n' and '\0• to new position. ********************************/ 
LineBuffer [Column + 2] = LineBuffer [LineLength - 1]; 

LineBuffer [Column + 1] = LineBuffer [LineLength -2]; 

/*** Fill line with spaces. *********************************************/ 
memset , , 

(LineBuffer + LineLength - 2, /* Destination. / 

i i /* Character to fill with. */ 

Column - LineLength + 2); /* Number of repetitions. */ 

/*** write character. ***************************************************/ 
LineBuffer [Column] = (char)Character? 

/*** Adjust line length. **********************^ 

LineTable [Line].LineLength = (unsigned char)Column + 3; 
return TRUE; 

/*** Otherwise, must insert character in middle of line. *********************/ 

else 

/*** if insert mode is active, move all characters right of insertion 

point one space to the right. **************************************/ 


if (Insert) 


(LineBuffer + Column + 1, 
LineBuffer + Column, 
LineLength - Column); 


/* Move block. */ 
/* Target. */ 
/* Source. */ 
/* Number of bytes. */ 


/*** Adjust line length. *******************************************/ 
-f+LineTable [ Line] . LineLength; 

*** Write^character. *************************************************^*/ 
LineBuffer [Column] = (char)Character; 
return TRUE; 


} /* end InsertChar */ 


• Figure 6.8: 

The function InsertChar of the example program (continued) 
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WinAlarm 

Purpose: 

Sounds the computer speaker. 

Prototype: 

BOOL APIENTRY WinAlarm 

(hwnd hwndDesktop, Desktop window handle 
(HWND DESKTOP). 

ULONG rgfType) / The type of alarm; can be one of the 

following values: 

WA_WARNING 

WA_NOTE 

WAERROR 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

The alarms generated by this function can be enabled and dis¬ 
abled, and also their frequency or duration modified, through 
the function WinSetSysValue. The constants passed to Win- 
SetSysValue to perform these adjustments are as follows: 

Value Identifier Purpose 

SV_ALARM Disable or enable the alarm 

generated by WinAlarm. 

SV_ALARMFREQ Set the alarm frequency. 

SV_ALARMDURATION Set the alarm duration. 

Related Functions: 

WinSetSysValue 


• Figure 6.9: 

The WinAlarm Presentation Manager function 
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moved via a fast intrasegment block-copy operation generated by the C 
function memmove, rather than character by character in a loop. Al¬ 
though the source and destination areas for this copy operation over¬ 
lap, memmove is designed to correctly handle overlapping areas. 

If the call to InsertChar returns an error code (FALSE), then the char¬ 
acter routine calls the Presentation Manager function WinAlarm (Fig¬ 
ure 6.9), which creates a warning sound that notifies the user that the 
line has reached its maximum length. The routine then stops processing 
by issuing a return statement. 

If the call to InsertChar is successful, the routine calls Winlnvalidate- 
Rect to cause repainting of the section of the window that displays the 
recently altered data. Specifically, the invalid rectangle is assigned 
the coordinates of the portion of the current line (CursorLine) extend¬ 
ing from the inserted character to the end of the line (or to the end of the 
window if the line extends beyond the right window border). The 
dimensions of the invalid rectangle are assigned to the four fields of the 
RECTL structure Rect (Rect.xLeft, Rect.xRight, Rect.yBottom, and 
Rect.yTop). If you study the expressions that calculate these values, you 
will notice that Rect.xRight is assigned the number of the pixel immedi¬ 
ately to the right of the area that needs to be invalidated, and that 
Rect.yTop is given the number of the pixel immediately above the rec¬ 
tangle containing the altered characters. These expressions thus seem to 
indicate a rectangle that is one pixel wider and higher than required. 
Under the Presentation Manager, however, rectangles are specified by 
giving the coordinates of the pixel at the lower left corner, and the coor¬ 
dinates of the first pixel above and to the right of the pixel at the upper 
right corner (rather than the coordinates of the upper right pixel itself). 

The routine then forces immediate repainting of the window by call¬ 
ing WinUpdateWindow. (Note that if this function were not called, a 
series of rapidly repeated characters generated by holding down a key 
would cause the cursor to move, but the new characters would not appear 
on the screen until the key was released. The WM_GTAR message nor¬ 
mally has a low priority; it is not posted to the window message queue 
until all prior messages in the queue have been processed.) 

Finally, the character routine moves the cursor one position to the 
right by ca llin g WinSendMsg to send a recursive WM_CHAR message 
for a -> key. When calling this function, the program assigns the follow¬ 
ing values to the message parameters that will be passed to the window 
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procedure: 


Field 


Value Assigned 


Hardware scan code 
Character code 
Virtual-key code 
Repeat count 
Keyboard control flags 


0 

0 

VK_RIGHT 

1 

KC VIRTUALKEY 


Because the KC_VIRTUALKEY bit of the flag word is set (and the 
KC_CHAR bit is off), the message is processed by the VirtKey function; 
the routine that processes the arrow keys was described in Chapter 5. 
Note that this routine provides another example of sending recursive 
messages to avoid duplicating code. After control returns from Win- 
SendMsg, the character routine returns TRUE to inform the system that 
the key was processed. 


The Tab Key 

The program does not insert tab characters directly into the file 
buffer. Rather, it replaces this character with the number of space char¬ 
acters required to move the cursor to the next tab stop. The Tab-key 
routine is listed in Figure 6.10; this routine first calculates the number of 


/*** Process a tab key by sending equivalent number of space characters. *****/ 

if (CHARMSG(&msg)->chr == '\t 1 ) 

{ 

Col = 5 - Cursored % 5; 
while (Col--) 

WinSendMsg /* Send space character message to self. */ 


(hwnd, /* client window handle. */ 

WM_CHAR, /* Character message. */ 

MPFROM2SHORT (KC_CHAR, 1), /* Character key. */ 

MPFROM2SHORT (• \0)); /* Space character. */ 

return TRUE; 


) /* end '\t' */ 


• Figure 610: 

The Tab-key routine 
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spaces between the current cursor position and the next tab stop (the 
column numbers of the tab stops are multiples of 5). It then inserts 
the calculated number of space characters into the file. Each blank is in¬ 
serted by sending a WM_CHAR message back to the window proce¬ 
dure, specifying the KC CHAR code and the space character. 

The Enter Key 

When you press the Enter key, the program inserts a new line into 
the file (provided that the insert mode is active; if the program is in 
overwrite mode, the cursor simply moves down one line and over to 
the first column). The routine for processing this key (listed in Figure 
6.11) follows the same four basic steps outlined in the section on Nor¬ 
mal Character Keys; for inserting a new line, however, these steps are 
more complex. 


/*** Process Enter key. ******************************************************/ 

if (CHARMSG(&msg)->chr == '\r') 

{ 

/*** if in insert mode, insert a new line into buffer. ******************/ 
if (Insert) 

/*** insert the line into file buffer. *****************************/ 
InsertLine (CursorLine, CursorCol); 

/*** Adjust 'TopLineMax' and scroll bar range for new file length. */ 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1) ; 


WinSendMsg /* Adjust scroll bar range. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFROM2SHORT (TopLine, 0) , /* Position. */ 

MPFROM2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable only if scroll possible. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

TopLineMax ? 1 : 0); /* Enable only if max. 1=0. */ 


/*** invalidate 'CursorLine 1 and all lines below. ******************/ 

Rect.xLeft = 0; 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 

Rect.yBottom = 0; 

WinlnvalidateRect 

(hwnd, 

&Rect, 

FALSE); 

® Figure 6.11: 

The Enter-key routine 
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/*** Force update of client window. ********************************/ 
WinUpdateWindow (hwnd); 

} /* end insert mode */ 

/*** Move cursor down one line. ********************************************y 
WinSendMsg /* Move cursor down. */ 

(hwnd, /* client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), 

MPFROM2 SHORT (0, VK_DOWN)) ; 

/*** Adjust 'LastCursorLine' if in insert mode. *************************/ 
if (Insert) 

LastCursorLine = CursorLine; 


/*** Move cursor to beginning of line. **********************************/ 
WinSendMsg /* Send Home key message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VK_H0ME)); /* Home key code. */ 

return TRUE; 


} /* end '\r' */ 


• Figure 6.11: 

The Enter-key routine (continued) 


First, if the insert mode is active, the routine calls the function Insert- 
Line, which is contained in the buffer-management module and is 
listed in Figure 6.12. This function is passed the numbers of the line and 
column containing the cursor (CursorLine and CursorCol), and inserts 
a new line into the file buffer immediately before the cursor position. 
InsertLine copies all characters contained in LineBuffer that are before 
the cursor position into a newly allocated block within the heap. It then 
moves the remaining characters in LineBuffer to the beginning of the 
buffer. Finally, it inserts a new entry into LineTable, immediately before 
the CursorLine entry, which contains the address of the newly allocated 
heap block. These steps are illustrated in Figure 6.13. Note that the pro¬ 
gram can call memmove to move the elements of LineTable using a 
single block-copy operation (rather than adjusting the array element by 
element), since this C library function properly handles overlapping 
source and target addresses. 

Rather than returning the error status to the calling program, Insert- 
Line handles errors internally. If the maximum number of lines (MAX¬ 
LINES) is exceeded, or if the storage capacity of the heap is reached, 
InsertLine directly terminates the program by calling ErrorQuit. In the 








void InsertLine (SHORT Line, SHORT Column) 

/* 

Inserts a new line into the file buffer, immediately before character 
given by 'Column', within the line given by 'Line'. 

*/ 

{ 

NPCH HeapOffset; /* Holds 16-bit heap offset. */ 

PCH HeapPointer; /* Holds far pointer to heap base. */ 

/*** Fatal error if maximum lines reached. ***********************************/ 
if (+4-LastLine >= MAXLINES) 

{ 

sprintf (Message,"maximum lines reached; line %d", _LINE_); 

ErrorQuit (Message); 

} 

/*** Adjust 'Column' to maximum position in line. ****************************/ 
if (Column > LineTable [Line].LineLength - 2) 

Column = LineTable [Line].LineLength - 2; 

/*** Allocate a block for characters in line before 'Column'. ****************/ 
HeapOffset = WinAllocMem 
(HHeap, 

Column + 2); 
if (HeapOffset == NULL) 

{ 

sprintf (Message,"out of heap memory; line %d", _LINE__); 

ErrorQuit (Message); 

} 

/*** Copy characters before 'Column' into new block. *************************/ 


movedata /* Intersegment block copy. */ 

(LineSelector, /* Source; selector of 'LineBuffer'. */ 

LineOffset, /* Source; offset of 'LineBuffer'. */ 

HeapSelector, /* Target: selector of heap. */ 

(unsigned)HeapOffset, /* Target: offset of new block. */ 

Column); /* Number of characters to copy. */ 


/*** construct a far pointer to new block in heap. ***************************/ 
HeapPointer = MAKEP (HeapSelector,HeapOffset); 

/*** Write newline and null to end of new line in heap. **********************/ 
*(HeapPointer + Column) = '\n'; 

*(HeapPointer + Column + 1) = '\0'; 

/*** Move character number 'Column' and all following characters to beginning 

of 'LineBuffer'. ********************************************************/ 
memmove /* Intrasegment block copy.*/ 

(LineBuffer, /* Target address. */ 

LineBuffer + Column, /* Source address. */ 

LineTable [Line].LineLength - Column); /* Bytes to move. */ 

/*** Adjust line length. *****************************************************/ 
LineTable [Line].LineLength -= (unsigned char)Column; 


• Figure 612: 

The function InsertLine of the example program 
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/ *** 

Move all members of 'LineTable* one position toward end of table. 

-k ★ * -k k y 


memmove 




(&LineTable [Line + 1], 

/* Target. 

V 


SLineTable [Line], 

/* Source. 

*/ 


(LastLine - Line) * sizeof (LineTable [0])) 

/* Bytes to move 

*/ 

/*** 

Assign address of new heap block to 'LineTable*. 

************************/ 


LineTable [Line].LineAddress = HeapPointer; 




LineTable [Line].LineLength = (unsigned char)(Column + 2); 



} /* end InsertLine */ 




• Figure 6.12: 

The function InsertLine of the example program (continued) 


current version of the example program, running out of memory is 
treated as a fatal error. 

Because the call to InsertLine changes the overall length of the file 
(that is, LastLine is incremented), the Enter-key routine must sub¬ 
sequently adjust the range of the vertical scroll bar. The routine per¬ 
forms this task by adjusting TopLineMax and by calling WinSendMsg 
and WinEnableWindow, in the same manner as the Size function (see 
the description of Size in Chapter 4 for an explanation of these steps). 

Next, the routine calls WinlnvalidateRect to invalidate the line con¬ 
taining the cursor and all lines displayed below it within the window, 
followed by the usual call to WinUpdateWindow to force immediate 
repainting. 

All of the steps described so far are performed only if the program is 
in the insert mode. Next, regardless of the mode, the program moves 
the cursor down one line and to the first column by sending recursive 
down-arrow and Home-key messages back to the client window proce¬ 
dure (this is the same technique that the normal character routine, 
described earlier, used to move the cursor). Note that if the program is 
in insert mode (and therefore a new line was inserted), LastCursorLine 
must be updated to the value in CursorLine, since CursorLine was in¬ 
cremented yet the cursor is still within the line stored in LineBuffer. 


The Backspace Key 

The effect of the Backspace key depends upon whether the cursor 
is in the first column (column 0) and whether the program is in the in¬ 
sert mode. The routine that processes this key is listed in Figure 6.14. 









CursorLine 


LineTable 


BEFORE CALLING 
InsertLine 



This line is about to be divided\n\0 
LineBuffer ^ 


Presentation Manager Heap 


CursorLine 


CursorLine +1 


LineTable 


AFTER CALLING 
InsertLine 




y 

f 

This line 

is ab|\n\0 

cursor 


jout to be divided\n\0 

^ LineBuffer 

Cursor will be 
moved here 


Presentation Manager Heap 


• Figure 6.13: 

Inserting a new line with the InsertLine function 








Programmer's Guide to the OS/2 Presentation Manager 


/*** Process a Backspace key. ************************************************^ 

if (CHARMSG(&msg)->chr == •\b•) 

{ 

/*** If cursor is at column 0, must join line to previous line. *********/ 
if (CursorCol == 0) ' 


{ 

/*** no previous line if cursor is in first line. ****************** 
if (CursorLine == 0) 
return TRUE; 


/ 


/*** Move cursor one line up. **************************************^ 
WinSendMsg /* Send up-arrow message to self. */ 

(hwnd, /* client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* A virtual key. */ 

MPFROM2SHORT (0, VK_UP)); /* Up-arrow code. */ 

/*** Move cursor to end of line. ***********************************y 

WinSendMsg /* send End message to self. */ 

(hwnd, /* client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* A virtual key. */ 

MPFROM2SHORT (0, VK_END)); /* End code. */ 

/*** jf i n overwrite mode, return without joining lines. ***********/ 
if (!Insert) 

return TRUE; 

/*** Join line to previous line. ***********************************/ 
if (UoinLine (CursorLine +1)) 

{ 

/*** Sound alarm if join fails (max line length exceeded). ****/ 
WinAlarm (HWND_DESKTOP, WA_ERROR); 
return TRUE; 

} 

/*** Adjust 'LastCursorLine'. **************************************/ 
LastCursorLine = CursorLine; 

/*** Adjust 'TopLineMax' and scroll bar range for new file length. */ 
TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 


WinSendMsg /* Send message to vertical scroll bar. 

(HVScroll, /* Recipient handle. 

SBM_SETSCROLLBAR, /* Set position & range. 

MPFROM2SHORT (TopLine, 0) , /* Position. 

MPFROM2SHORT (0, TopLineMax));- /* Range. 


WinEnableWindow 

(HVScroll, 

TopLineMax ? 1 : 0) ; 


/* Enable only scroll possible. 
/* Recipient handle. 

/* Enable only if max. != 0. 


V 

V 

V 

V 

V 

*/ 

V 

V 


/*** invalidate joined line and all lines below. *******************/ 


• Figure 6.14: 

The Backspace-key routine 




Rect.xLeft = 0; 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 

Rect.yBottom = 0; 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* Don't include descendants w/ WS_CLIPCHILDREN*/ 

/*** Force window update. ******************************************/ 
WinUpdateWindow (hwnd); 

/*** TRUE signals that key was processed. **************************/ 
return TRUE; 

} /* end cursor at column 0 */ 

/*** Remaining code is for cursor NOT at column 0. **********************/ 

/*** Move cursor back one space. ****************************************/ 
WinSendMsg /* Send left-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFR0M2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VK_LEFT)); /* Left-arrow code. */ 

/*** if in insert mode, delete character. *******************************/ 
if (Insert) 

WinSendMsg /* Send Del message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFR0M2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFR0M2SHORT (0, VK_DEL)) ; /* Del key code. */ 

/*** jf in overwrite mode, overwrite current character with a space. ****/ 
else 

/*** Print a space character. **************************************/ 
WinSendMsg /* Send space character message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character message. */ 

MPFROM2SHORT (KC_CHAR, 1), /* Character key. */ 

MPFROM2SHORT (' ’,0)); /* Space character. */ 

/*** Restore cursor position (printing space advanced it!). ********/ 
WinSendMsg /* Send left-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VKJLEFT)) ; /* Left-arrow code. */ 

} /* end overwrite mode */ 

/*** signal system that key was processed. *******************************/ 
return TRUE; 

} /* end '\b' */ 


Figure 6.14: 

The Backspace-key routine (continued) 
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If the cursor is beyond the first column and the program is in insert 
mode, the Backspace-key routine moves the cursor back one space by 
sending a left-arrow message to the window procedure, and then 
deletes the character at the new position by sending a Del-key message 
(the Del key is processed by the VirtKey routine, discussed later in the 
chapter). If the program is in the overwrite mode, then the routine 
moves the cursor back one space, and writes a space character at the 
new position by sending a character message; it must then send a left- 
arrow message to restore the cursor position (writing the space ad¬ 
vanced the cursor; the cursor, however, should remain at the newly 
blanked position). Note that many editors do not distinguish between 
insert and overwrite modes when performing a backspace operation; 
however, replacing the preceding character with a space rather than 
deleting it prevents shifting left all the remaining characters in line. A 
design goal of the example editor is that in the overwrite mode, editing 
operations should not normally alter the relative positions of characters 
(exceptions are the F9 and Del keys). 

If the cursor is at column 0 and the program is in insert mode, then 
the routine joins the current line with the previous line, conceptually 
deleting the preceding newline character (provided, of course, that the 
cursor is not in the first line of the file). Note that using the Backspace 
key to join lines is one of two common options; alternatively, many 
editors join lines when you press the Del key at the end of the preceding 
line (and some editors use both methods). 

The backspace routine joins lines by moving the cursor to the end of 
the previous line and calling the function JoinLine, which is part of the 
buffer-management module and is listed in Figure 6.15. JoinLine is 
passed the number of the line that is contained in LineBuff er (which, at 
this point, is CursorLine + 1); it first moves the characters in this line far 
enough toward the end of the buffer to make room for the characters 
belonging to the previous line. It then copies the characters from the 
previous line into the beginning of LineBuffer. Finally, JoinLine frees 
the heap memory occupied by the previous line, and deletes the cor¬ 
responding entry from LineTable. These operations are illustrated in 
Figure 6.16. 

If JoinLine returns an error code (FALSE), the backspace routine 
sounds the alarm by calling WinAlarm and returns. Otherwise, it per¬ 
forms the standard tasks of adjusting the vertical scroll bar range and 
invalidating the affected area of the window. 
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int JoinLine (SHORT Line) 

/* 

Combines the line in the file buffer given by 'Line' with the previous 
line. 

*/ 

{ 

/*** Return if 'Line' is the first in the file (no previous line). ***********/ 
if (Line == 0) 

return FALSE; 

/*** Return if combined length would exceed maximum line length. *************/ 
if (LineTable [Line].LineLength + LineTable [Line - 1].LineLength - 2 > 
LINEBUFSIZ) 
return FALSE; 

/*** Move existing characters in 'LineBuffer' to right to make room for the 


characters from previous line. ******************************************/ 
meramove 

(LineBuffer + LineTable [Line - 1].LineLength - 2, /* Target. */ 
LineBuffer, /* Source. */ 

LineTable [Line].LineLength); /* Number of bytes. */ 

/*** Move the characters from previous line to beginning of 'LineBuffer'. ****/ 
movedata 

(SELECTOROF (LineTable [Line - 1].LineAddress), /* Source. */ 

OFFSETOF (Li ne Table [Line - 1].LineAddress), /* Source. */ 

LineSelector, /* Target. */ 

LineOffset, /* Target. */ 

LineTable [Line - 1].LineLength - 2); /* Bytes to copy.*/ 

/*** Adjust line length for added characters. ********************************/ 
LineTable [Line].LineLength += LineTable [Line - 1].LineLength - 2; 

/*** Free block used by previous line. ***************************************/ 
if (WinFreeMem 

(HHeap, /* Handle of heap from 'WinCreateHeap 1 . */ 

(BYTE NEAR *)0FFSET0F (LineTable [Line-1].LineAddress), /* Offset. */ 
LineTable [Line-1].LineLength) /* Length of block to free. */ 

1= NULL) 

{ 

sprintf (Message,"managing heap; line %d",_LINE_); 

ErrorQuit (Message); 

} 


/*** Move all 'LineTable' members above and including 'Line' down one place. */ 
memmove 

(ScLineTable [Line - 1], /* Destination. */ 

SLineTable [Line], /* Source. */ 

(LastLine - Line + 1) * sizeof (LineTable [0])) ; /* Bytes to move.*/ 

/*** Adjust 'LastLine'. ******************************************************/ 
—LastLine; 

return TRUE; 

} /* end JoinLine */ 


© Figure 6.15: 

The function JoinLine of the example program 
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® Figure 6.16: 

Joining two lines with the JoinLine function 
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Finally, if the cursor is in column 0 and .the overwrite mode is active, 
the backspace routine simply moves the cursor to the end of the pre¬ 
vious line without joining the two lines (in keeping with the philosophy 
that operations in the insert mode should not alter the relative positions 
of characters). 


• THE VIRTUAL KEYS 

When the main client window procedure, WndProc, detects that 
the WM_CHAR message contains a valid virtual code, it calls the Virt- 
Key function to process the key This function branches to the ap¬ 
propriate routine according to the virtual code that identifies the 
specific key, using the following switch statement: 

switch (CHARM3G (&msg)->vkey) 

The codes for the virtual keys are listed in Table 6.1. VirtKey contains 
routines for the following subset of these keys: 


Key 

Virtual Code 

Routine 

T ' 

VK_UP 

Figure 5.11 

i 

VK_DOWN 

Figure 5.11 

<r~ 

VK_LEFT 

Figure 5.11 

— > 

VK_RIGHT 

Figure 5.11 

PgUp 

VK_PAGEUP 

Figure 5.14 

PgDn 

VK_PAGEDOWN 

Figure 5.14 

Home 

VK HOME 

Figure 5.13 

End 

VK END 

Figure 5.13 

F9 

VK_F9 

Figure 6.17 

Delete 

VK_DELETE 

Figure 6.19 

Insert 

VKJNSERT 

(in Figure 6.24) 


If the virtual code is not one of those listed above, VirtKey returns 
the value FALSE, indicating that the message was ignored. Note that 
the only routines not already discussed in Chapter 5 are those for the F9 
key, the Del key, and the Ins key. 
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The F9 Key 

In response to the F9 key, the program erases the entire line con¬ 
taining the cursor. The routine that handles this key is listed in Figure 
6.17. The routine first calls the function DeleteLine, which belongs to 
the buffer-management module and is listed in Figure 6.18. DeleteLine 
is passed the address of the line containing the cursor (CursorLine) and 
performs the following three tasks: 

m It calls GetTempBuf, passing it the number of the line that 
follows the line to be deleted. GetTempBuf (listed in Figure 6.5 
and explained earlier in the chapter) copies this following line 


/*** process F9 key: delete line containing cursor. ********************/ 
case VK_F9: 

/*** if modifying a new line, must place line in temporary buffer. */ 
if (LastCursorLine != CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

} 

/*** Delete line containing the cursor. ****************************/ 
DeleteLine (CursorLine); 


/*** Adjust ’TopLineMax’ and scroll bar range for new file length. */ 
TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

WinSendMsg 

(HVScroll, /* Recipient handle. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFROM2SHORT (TopLine, 0) , /* Position. */ 

MPFROM2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow 

(HVScroll, /* Recipient handle. */ 


TopLineMax ? 1 : 0); /* Enable only if max.!= 0*/ 

/*** invalidate ’CursorLine' and all lines below. ******************/ 


Rect.xLeft = 0; 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 

Rect.yBottom = 0; 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* No descendants w/ WS_CLIPCHILDREN. */ 

WinUpdateWindow (hwnd); /* Force updating of client window. */ 


return TRUE; 


• Figure 6.17: 
The F9 routine 
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void DeleteLine (SHORT Line) 

/* 

Deletes the specified line ('Line', which must be the line currently 
containing the cursor) from the file buffer. 

V 

{ 

/*** if line to be deleted is the last file line, merely truncate it. ********/ 
if (Line == LastLine) 

{ 

LineBuffer [0] = '\n'; 

LineBuffer [1] = '\0' ; 

LineTable [Line].LineLength = 2; 

} 

else 

{ 

/*** place the following line into 'LineBuffer 1 . ************************/ 
GetTempBuf (Line + 1) ; 


/*** Move all LineTable elements beyond deleted 

line down 

one element. 

**/ 

memmove 




(&LineTable [Line], 

/* 

Target. 

V 

SLineTable [Line + 1], 

/* 

Source. 

*/ 

(LastLine - Line) * sizeof (LineTable 

[0])); /* 

Number bytes. 

*/ 


--LastLine; 

} 


} /* end DeleteLine */ 


® Figure 6.18: 

The function DeleteLine of the example program 

into LineBuffer (writing over the deleted line) to ready it for 
editing. 

• It deletes the entry in LineTable for the line that is being 
removed by moving all entries above this entry one position 
toward the beginning of the array. Again, the array manipulation 
is performed using a fast block-copy operation generated by the 
memmove function. 

• It decrements LastLine. 


If, however, the line to be deleted is the last in the file, DeleteLine simp¬ 
ly truncates this line by writing the y \n' and AO' characters to the first 
two positions in LineBuffer. 

After calling DeleteLine, the F9 routine must adjust the vertical scroll 
bar range for the new file length. It performs this task in the same man¬ 
ner as the Enter routine and the Size function. Next, it invalidates the 
line containing the cursor—and all lines displayed below it—by calling 
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WinlnvalidateRect. Finally, it calls WinUpdateWindow to force imme¬ 
diate repainting of the invalid lines. Note that deleting a line causes all 
lower lines to scroll up one position, while the cursor remains in its 
same position; therefore, the F9 routine does not have to send a message 
to reposition the cursor. 

The Del Key 

The routine for the Del key is listed in Figure 6.19. Since this key 
causes modification of the line containing the cursor, the routine issues 
a sequence of instructions that assure that this line is held in the tem¬ 
porary modification buffer (LineBuffer). These instructions are the 
same as those at the beginning of the Character routine, explained ear¬ 
lier in the chapter. 

The Del-key routine next calls the function DeleteChar (Figure 6.20), 
belonging to the buffer-management module. This function is passed 
the row and column positions of the character currently containing the 
cursor (CursorLine and CursorCol), and it deletes this character from 
LineBuffer. Note that when deleting a given character from the line, 
DeleteChar moves all characters beyond it one space left. 

If the specified character position is beyond the end of the line 
(caused by pressing the Del key when the cursor is positioned past the 
last character), DeleteChar returns FALSE and the Del-key routine 
simply returns without performing any action (this occurrence is not an 
error; there is simply no key to delete). If DeleteChar returns TRUE, 
indicating that the character was successfully deleted, the routine in¬ 
validates the region of the window that displays the altered data. 
(Specifically, the invalid rectangle is assigned the coordinates of the por¬ 
tion of the current line extending from the inserted character to the end 
of the line, or to the end of the window if the line extends past the right 
border.) 

Note that the Del-key routine does not distinguish between the insert 
mode and the overwrite mode. 


The Ins Key 

The Ins-key routine simply toggles the value of the global flag 
Insert between 1 and 0, using the following expression: 

Insert A = 1; 
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/*** Process Del key. ***************************************************/ 
case VK_DELETE: 

/*** if modifying a new line, must place line in temporary buffer. */ 
if (LastCursorLine != CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

} 

/*** Delete character from file buffer. ****************************/ 
if (DeleteChar (CursorLine,Cursored)) 

{ 

/*** if deletion successful, invalidate window from cursor 

position to end of line. *********************************/ 

Rect.xLeft = (Cursored - FirstCol) * xChar; 

Rect.xRight = min 

((GetLineLength (CursorLine) + 1 - FirstCol) * xChar, 
xWin); 

Rect.yBottom = yWin - (CursorLine - TopLine +1) * yCharTot; 
Rect.yTop = Rect.yBottom + yCharTot; 

WinlnvalidateRect /* Invalidate region to be updated. */ 
(hwnd, 

&Rect, 

FALSE); 

WinUpdateWindow (hwnd); /* Force client window update. */ 
return TRUE; 


• Figure 6.19: 

The Del-key routine 


As mentioned earlier in the chapter, when this flag is 1, the program 
is in the insert mode, and when it is 0, it is in the overwrite mode. Since 
Insert is initialized to 1, the program begins in the insert mode. All 
routines within the program that depend upon the state of this mode 
directly test Insert (for example, the Backspace-key routine, described 
in the previous section). Note that the version of the program presented 
in Chapter 7 will allow you to select modes through a menu item; in this 
version. Ins will be designated as an accelerator key (explained in Chap¬ 
ter 7) and will be processed directly by the menu routine rather than 
through the VirtKey function. 
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int DeleteChar /* Deletes a character from ’LineBuffer 1 . */ 

(SHORT Line, /* Line containing character to be deleted. */ 

SHORT Column) /* Number of character to be deleted. */ 

/* 

This function deletes the indicated character from 'LineBuffer*. It 
returns TRUE if the buffer was modified, and FALSE if no action took 
place (i.e., the specified character was beyond the visible end of the 
line). 

V 

{ 

/*** Return FALSE if character is beyond visible length of line. *************/ 
if (LineTable [Line].LineLength <3 j | 

Column > LineTable [Line].LineLength - 3) 
return FALSE; 

/*** Move all characters beyond deleted character one place left. ************/ 
memmove 

(LineBuffer + Column, /* Target. */ 

LineBuffer + Column +1, /* Source. */ 

LineTable [Line].LineLength - Column - 1); /* Number of bytes. */ 

/*** Adjust line length. *****************************************************/ 
—LineTable [Line].LineLength; 

return TRUE; 

} /* end DeleteChar */ 


© Figure 6.20: 

The function DeleteChar of the example program 


• EDITING A NEW FILE 

Since the current version of the example program allows you to 
add data to the file, it should permit opening a new file. Consequently, 
if you specify a file name on the command line when starting the pro¬ 
gram, this file is read into the buffer as in the previous version. How¬ 
ever, if you do not specify a file name, then rather than terminating with 
an error message, the current version of the program calls the function 
NewFile, belonging to the buffer-management module and listed in 
Figure 6.21. 

NewFile initializes the buffer for a new empty file. It allocates a heap 
having an initial size of 4096 bytes; remember, however, that the Presen¬ 
tation Manager will automatically expand the heap if it requires more 
memory to satisfy an allocation request. 
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void NewFile (void) 

/* 

Initializes the file buffer for a new empty file. 

*/ 

{ 

PCH FarPtr; /* Temporary far character pointer. */ 

/*** Initialize 'LineBuffer'. ************************************************/ 
LineBuffer [0] = '\n'; 

LineBuffer [1] = ’\0*; 

/*** Initialize 'LineTable' for first (and only) line. ***********************/ 
LineTable [0].LineAddress = MAKEP (LineSelector, LineOffset); 

LineTable [0].LineLength = 2; 

/*** Initialize 'LastLine 1 . **************************************************/ 
LastLine = 0; 

/*** create a heap to hold data added to file. *******************************/ 
HHeap = WinCreateHeap 


(0, 

/* 

Segment 

address: 0 means allocate 

new segment. 

*/ 

4096, 

/* 

Initial 

heap size. 


V 

o, 

/* 

Minimum 

increase size: 0 means use 

default. 

V 

o, 

/* 

Minimum 

# of dedicated free lists: 

none. 

*/ 

o, 

/* 

Maximum 

# of dedicated free lists: 

none. 

V 

HM MOVEABLE); 

/* 

Options: 

: support movable objects. 


*/ 


/*** obtain selector address of heap. ****************************************/ 
FarPtr = WinLockHeap (HHeap); 

HeapSelector = SELECTOROF (FarPtr)? 

) /* end NewFile */ 


® Figure 6.21: 

The function NewFile of the example program 


• ENHANCEMENTS 

This section offers three suggestions for enhancements to the 
present version of the example program: 

• Using inline code for displaying single characters 

• Eliminating trailing blanks 

• Converting tab characters 
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Inline Display Code 

One of the design goals of the example program is to centralize all 
code for painting the window within a single routine. As you have seen 
in this chapter, all updating of the characters displayed in the window 
occurs through the Paint function, which processes the WMJPAINT 
message. When any other routine in the system needs to modify the 
window data, it simply invalidates the appropriate section of the win¬ 
dow, which forces the system to issue a WM_PAINT message; the func¬ 
tion Paint then obtains the coordinates of the invalid area and displays 
the current characters from the file buffer within this area. 

Centralizing all display code within a single routine makes the pro¬ 
gram shorter, simpler, and easier to maintain. However, the process of 
invalidating a window region and generating a paint message is quite 
time-consuming. The time overhead is especially excessive for display¬ 
ing a single character. You can process single characters typed at the end 
of the line more efficiently if you place a special duplicate version of the 
display code directly within the appropriate routine in the Character 
function (the current routine is listed in Figure 6.7). If the character is 
not typed at the end of the line and the program is in insert mode, it 
is probably best to use the present method, since more than one charac¬ 
ter will have to be displayed. 

By locating the code for displaying single characters within the Char¬ 
acter function, you can save the overhead of the function calls to Win- 
InvalidateRect, WinUpdateWmdow, and Paint, and you can eliminate 
the calculation of the start and stop lines and the for loop logic. If you 
place the display code within the character-handling routine, however, 
you should observe the following general guidelines (except for these 
guidelines, the routine can use the same method employed by the Paint 
function): 

• Obtain and release the presentation space using the WinGetPS 
function (Figure 3.20) and the WinReleasePS function (Figure 
3.21), rather than WinBeginPaint and WinEndPaint (which 
should be called only during processing of the WM_PAINT message). 

• Hide the cursor before displaying the character, and make it 
visible afterward, by calling WinShowCursor (Figure 5.5). Other¬ 
wise, the cursor will not be erased from the character cell, and 
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multiple copies of the cursor will appear across the window. 

(The system automatically performs this task when you call Win- 
BeginPaint and WinEndPaint.) 

• Rather than explicitly erasing the area to be occupied by the new 
character (through WinFillRect), you can call the Presentation 
Manager function GpiSetBackMix (Figure 9.8), before calling 
GpiCharStringAt, as follows: 

GpiSetBackMix (HPresSpaceBM_OVERPAXNT) ; 

This function call causes GpiCharStringAt to overwrite the back¬ 
ground within the character cell with its default background 
color. Otherwise, GpiCharStringAt paints only the foreground 
pixels and leaves the background unaltered; the result is that the 
old character is not erased and the new character is written 
directly on top of it. Note that if the default background color is 
not the same as the window background (white in the example 
program, generated by WinFillRect), you may have to call Gpi- 
SetBackColor (Figure 9.9) to set the background color used by 
GpiCharStringAt within the specified presentation space. 

The length parameter passed to GpiCharStringAt should be 1L and 
the string parameter should be the address of the single character that 
was entered (CHARMSG (&msg)->chr). Writing characters using 
direct inline code is dramatically faster that the indirect method 
employed by the example program, and the difference in speed is espe¬ 
cially noticeable when holding down a character key to generate 
repeated keystrokes. 


Eliminating Trailing Blanks 

When blank characters are entered at the end of a line, these char¬ 
acters are saved in the file buffer and remain there even if the line is not 
subsequently terminated with one or more nonblank characters. Since 
these terminating blanks waste valuable file space, you might want 
to eliminate them when the user moves the cursor away from the cur¬ 
rent line and begins modifying another line. A good point within the 
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program to remove trailing blanks would be in the function Release- 
TempBuf, before (or as) the line is copied from LineBuffer to the heap. 


Converting Tab Characters 

Although the program converts all tab characters entered from the 
keyboard into the equivalent number of spaces, and does not insert tabs 
into the file buffer, it makes no provision for converting tab characters 
contained in a file read into the buffer (such tabs could have been 
entered by another editor). GpiCharStringAt does not properly display 
tabs (they appear as small circles). Therefore, you might want to modify 
the ReadFile function to convert tab characters to the appropriate num¬ 
ber of spaces as each line is read from the file. 


• CONCLUSION 

A MAKE file for preparing the current version of the example pro¬ 
gram is given in Figure 6.22, and the linker definition file is in Figure 
6.23. The complete source code listing appears in Figure 6.24. 

The example program at its current state of evolution provides most 
of the basic editing functions for modifying or creating a text file. The 
next logical step is to allow you to save the modified version of the file, 
and to perform other file functions such as reading a new file. The file 
functions will be accessed through a Presentation Manager menu, and 
the file names will be entered through a dialog box. Therefore, although 
the routines for performing these operations are simple, they are not in¬ 
troduced until dialog boxes have been added in Chapter 8. 


# Figure 6.22 

# This MAKE file prepares the program of Figures 6.23 and 6.24 

# 

FIG6_2 4.OBJ : FIG6_24.C 

cl /W2 /c /Zp /G2ws FIG6_24.C 

FIG6_24.EXE : FIG6_24.0BJ FIG6_23.DEF 

link /NOD FIG6_24.OBJ, , NUL, OS2.LIB SLIBCE.LIB, FIG6_23.DEF 


® Figure 6.22: 

A MAKE file for preparing the example program 
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Figure 6.23 

Linker definition file for the program listed in Figure 6.24 


NAME 

PROTMODE 

HEAPSIZE 

STACKSIZE 

EXPORTS 


FIG6_2 4 

1024 

8192 

WndProc 


@ Figure 6.23: 

A linker definition file for preparing the example program 


/* 

Figure 6.24 

Version 4 of the Presentation Manager text editor example program. 

This version adds the following features: 

o Displays a cursor indicating the current insertion point, which can be 
moved with the arrow and Home/End keys 
o Permits creating a new file as well as reading in an existing file 
o Allows you to add characters and lines to the file 

o Supports both insert and overwrite modes (toggled with the Ins key) 
o Backspace and Del keys can be used to delete characters 
o Backspace key can be used to join lines 
o Ctrl-Y key can be used to delete complete lines 

o Tab key is converted to the equivalent number of space characters 

*/ 

#define INCL_GPI /* Include all Gpi... function declarations. */ 

#define INCL_WIN /* Include all Win... function declarations. */ 

#include <0S2.H> 

#include <STDIO.H> /* C library header files: */ 

#include <PROCESS.H> 

^include <10.H> 

#include <STRING.H> 

#include <STDLIB.H> 


@ Figure 6.24: 

The source code file for the example program 





Programmer's Guide to the OS/2 Presentation Manager 


/*** window procedure declaration. 


MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


/*** Declarations / definitions for file- and buffer-management module. ******/ 

#define LINEBUFSIZ 255 


/* Size of buffer for holding lines. 

*/ 

^define ERROPEN 1 


/* Error: opening file. 

*/ 

#define ERRTOOBIG 2 


/* Error: file too large. 

*/ 

#define ERRMAXLINES 3 


/* Error: maximum file lines exceeded. 

*/ 

#define ERRALLOC 4 


/* Error: heap allocation. 

*/ 

void Buflnit (void); 


/* Initializes buffer-management module. 

*/ 



/* Deletes character from buffer: 

*/ 

int DeleteChar (SHORT Line, 5 

SHORT 

Column); 


void DeleteLine (SHORT Line) 


/* Deletes the current line. 

*/ 

. char *ErrorMessage (int ErrorNumber); /* Returns error message string. 

*/ 

! PCH GetLineAddr (int Line); 


/* Gets address of line in buffer. 

*/ 

SHORT GetLineLength (int Line); 

/* Gets length of line in buffer. 

*/ 

void GetTempBuf (int Line); 


/* Obtains a temporary line buffer. 

*/ 



/* Inserts character into buffer: 

*/ 

int InsertChar (SHORT Line,USHORT 

Character,SHORT Column, int Overwrite); 




/* Inserts new line into buffer. 

*/ 

void InsertLine (SHORT Line, 

SHORT 

Column); 


int JoinLine (SHORT Line); 


/* Joins line to previous line. 

*/ 

void NewFile (void); 


/* Clears buffer for a new file. 

*/ 

int ReadFile (char *FileName) 

; 

/* Reads file into editor buffer. 

*/ 

void ReleaseTempBuf (int Line); 

/* Releases temporary line buffer. 

*/ 

int LastLine = -1; 


/* Number of last line in buffer. 

*/ 

HHEAP HHeap = NULL; 


/* PM heap handle. 

V 

/*** Utility function declarations 

. ******************************************/ 

void ErrorQuit (char ^Message); 

/* Print error message, end program. 

*/ 

void Quit (int ErrorCode); 


/* Terminate the PM program. 

*/ 

/*** Global variables. *******************************************************/ 

HWND HFrame; 


/* Handle to main frame window. 

*/ 

HAB HAncBlk; 


/* Handle to anchor block. 

*/ 

HMQ HMesQue; 


/* Message queue handle. 

V 

char Message [64]; 


/* Buffer for displaying error messages. 

*/ 

void main (int argc, char *argv[]) 



\ 

int ReadError = 0; 


/* Error occurred reading file. 

V 

HWND HClient; 


/* Handle to main client window. 

*/ 

QMSG QueMess; 


/* Message structure. 

*/ 

ULONG CtlData = 


/* Control windows to include. 

V 

FCF HORZSCROLL 


/* Horizontal scroll bar. 

*/ 

FCF MINMAX 


/* Minimize/maximize box. 

V 

FCF SHELLPOSITION 


/* Make window visible on screen. 

V 

FCF SIZEBORDER 


/* Wide sizing border. 

V 

FCF SYSMENU 


/* System menu. 

V 


Figure 6.24: 

The source code file for the example program (continued) 
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FCF 

TASKLIST ! 

/* 

Display program name in Task Manager. 

*/ 

fcf" 

TITLEBAR 

/* 

Title bar. 

*/ 

fcf" 

VERTSCROLL; 

/* 

Vertical scroll bar. 

*/ 


BufInit (); 

/*** if no file specified, open a new file. *********************************/ 

if (argc < 2) 

NewFile (); 

else 

ReadError = ReadFile (argv [1])? 


HAncBlk = Winlnitialize (0); /* Initialize PM system for process. */ 

HMesQue = WinCreateMsgQueue (HAncBlk,0); /* Create a message queue. */ 

WinRegisterClass /* Register procedure for main window. */ 

(HAncBlk, /* Anchor block handle. */ 

"MAIN", /* Window class name. */ 

WndProc, /* Window procedure associated w/ class. */ 

0L, /* Class style. */ 

0); /* Extra storage bytes. */ 

HFrame = WinCreateStdWindow /* Create parent window. */ 

(HWND_DESKTOP, /* Parent window handle. */ 

WS_VISIBLE, /* Frame window style. */ 

&CtlData, /* Address of control data. */ 

"MAIN", /* Client window class name. */ 

": PM Text Editor", /* Text for title bar. */ 

0L, /* Client window style. */ 

0, /* Resource module handle. */ 

0, /* Resource identification. */ 

SHClient); /* Address to receive client window hand. */ 

if (ReadError) /* Quit if read error. */ 

ErrorQuit (ErrorMessage (ReadError)); 

WinSetFocus /* Give focus to client window. */ 

(HWND_DESKTOP, /* Handle for desktop window. */ 

HClient); /* Client window handle. */ 

while (WinGetMsg /* Get messages until WM_QUIT. */ 

(HAncBlk, /* Anchor block handle. */ 

&QueMess, /* Address of message structure. */ 

0, /* Window filter. */ 

0, /* First message identifier. */ 

0)) /* Last message identifier. */ 

WinDispatchMsg (HAncBlk,SQueMess); /* Dispatch messages. */ 

Quit (0); /* Normal termination. */ 


} /* end main */ 


® Figure 6.24: 

The source codefile for the example program (continued) 





/*** Window procedure and subroutines. ***************************************/ 

MRESULT EXPENTRY Character 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY Create 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY HScroll 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY Paint 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY SetFocus 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY Size 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY VirtKey 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY VScroll 

(HWND 

hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


static SHORT xChar; 

/* 

Character width. 

*/ 

static SHORT yCharTot; 

/* 

Total height of characters. 

*/ 

static SHORT yCharDesc; 

/* 

Height of character descenders. 

*/ 

static SHORT xWin; 

/* 

Horizontal size of window. 

*/ 

static SHORT yWin; 

/* 

Vertical size of window. 

*/ 

static HWND HVScroll; 

/* 

Handle to vertical scroll bar window. 

*/ 

static HWND HHScroll; 

/* 

Handle to horizontal scroll bar window. 

*/ 

static int FirstCol; 

/* 

Character to be in first column position. 

*/ 

static int FirstColMax; 

/* 

Maximum value of 'FirstCol'. 

V 

static SHORT TopLine = 0; 

/* 

Number of top line in window. 

V 

static SHORT TopLineMax; 

/* 

Maximum value of 'TopLine'. 

*/ 

static FATTRS FontAttributes; /* 

Stores font attributes from GpiQueryFonts. 

V 

/*** Cursor-management variables. 

********************************************/ 

static SHORT CursorLine = 0; 

/* Current line location of cursor. 

*/ 

static SHORT CursorCol = 0; 


/* Current column location of cursor. 

*/ 

static SHORT LastCursorLine 

= 0; 

/* Last line position of cursor. 

*/ 

/*** Flag for insert mode. 

***************************************************/ 

static int Insert = 1; 




#define ID_COURIER 99L 

/* 

Local font ID. 

*/ 

MRESULT EXPENTRY WndProc 




(HWND hwnd, 

/* 

Window handle. 

*/ 

USHORT msg, 

/* 

The message. 

*/ 

MPARAM mpl, 

/* 

Message-specific information. 

*/ 

MPARAM mp2) 

/ 

/* 

Message-specific information. 

*/ 

l 

char Buffer [81]; 




switch (msg) 




( 

case WM CHAR: 

/* 

Message sent when keyboard key is received. 

*/ 

/*** Don't process a key-released message. *************************/ 

if ( CHARMSG 

( &msg)->fs & KC KEYUP) 


return 

FALSE ; 


/*** Process character 

key„ ****************************************/ 

else if (CHARMSG 

( &msg)->fs & KC CHAR) 


return 

Character (hwnd, msg, mpl, mp2) ; 


/*** Process virtual key. ******************************************/ 

else if (CHARMSG 

( &msg)->fs & KC VIRTUALKEY) 


return 

VirtKey (hwnd, msg, mpl, mp2) ; 



© Figure 6.24: 

The source code file for the example program (continued) 
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/*** Don't process invalid key. ************************************/ 
else /* Invalid key: neither virtual nor character.*/ 

return FALSE; 

case WM CREATE: /* Message sent when window is first created. */ 

return Create (hwnd, msg, mpl, mp2); 

case WM HSCROLL: /* Message sent on horizontal scroll activity. */ 

return HScroll (hwnd, msg, mpl, mp2); 

case WM PAINT: /* Message sent when window data is invalid. */ 

return Paint (hwnd, msg, mpl, mp2); 

case WM SETFOCUS: /* Message sent when client focus changes. */ 

return SetFocus (hwnd, msg, mpl, mp2); 

case WM SIZE: /* Message sent whenever window changes size. */ 

return Size (hwnd, msg, mpl, mp2); 

case WM VSCROLL: /* Message sent on vertical scroll activity. */ 

return VScroll (hwnd, msg, mpl, mp2); 

default: /* Perform default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} /* end switch */ 

} /* end WndProc */ 

/*** Subroutines called by window procedure. *********************************/ 

MRESULT EXPENTRY Character (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* 

This function processes character keys (that is, keys with a valid ASCII 
code). 


register int Col; 
RECTL Rect; 


/* Used for loop to generate tab characters. */ 
/* Holds coordinates of rectangle. */ 


/*** if modifying a new line, must place line in temporary buffer. ***********/ 

if (LastCursorLine 1= CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

} 

/*** Process a Backspace key. ************************************************/ 
if (CHARMSG(&msg)->chr == '\b*) 

/*** if cursor is at column 0, must join line to previous line. *********/ 
if (Cursored == 0) 

{ _____ 


Figure 624: 

The source codefile for the example program (continued) 
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kf/4 


/*** NO previous line if cursor is in first line. ******************/ 
if (CursorLine == 0) 
return TRUE; 


/*** Move cursor one line up. **************************************/ 
WinSendMsg /* Send up-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* A virtual key. */ 

MPFROM2SHORT (0, VK_UP)) ; /* Up-arrow code. */ 

/*** Move cursor to end of line, a**********************************/ 

WinSendMsg /* Send End message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFR0M2SHORT (KC_VIRTUALKEY, 1), /* A virtual key. */ 

MPFROM2SHORT (0, VK_END)) ; /* End code. */ 


/*** If i n overwrite mode, return without joining lines. ***********/ 
if (!Insert) 

return TRUE; 

/*** join line to previous line. ***********************************/ 
if (UoinLine (CursorLine +1)) 

{ 

/*** Sound alarm if join fails (max line length exceeded). ****/ 
WinAlarm (HWND_DESKTOP, WA_ERR0R); 
return TRUE; 

) 

/*** Adjust 'LastCursorLine'. **************************************/ 
LastCursorLine = CursorLine; 

/*** Adjust 'TopLineMax' and scroll bar range for new file length. */ 
TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 


WinSendMsg /* Send message to vertical scroll bar. */ 

(HVScroll, /* Recipient handle. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable only scroll possible. */ 

(HVScroll, /* Recipient handle. */ 

TopLineMax ? 1 : 0); /* Enable only if max. 1=0. */ 


/*** invalidate joined line and all lines below. *******************/ 

Rect.xLeft = 0; 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 
Rect.yBottom = 0; 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* Don't include descendants w/ WS_CLIPCHILDREN*/ 


© Figure 624: 
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/*** Force window update. ******************************************/ 
WinUpdateWindow (hwnd); 

/*** TRUE signals that key was processed. **************************/ 
return TRUE; 

} /* end cursor at column 0 */ 

/*** Remaining code is for cursor NOT at column 0. **********************/ 

/*** Move cursor back one space. ****************************************/ 
WinSendMsg /* Send left-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VK_LEFT)) ; /* Left-arrow code. */ 

/*** If in insert mode, delete character. *******************************/ 
if (Insert) 

WinSendMsg /* Send Del message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character received message. */ 

MPFR0M2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFR0M2SHORT (0, VK_DELETE))? /* Del key code. */ 

/*** if in overwrite mode, overwrite current character with a space. ****/ 
else 

/*** print a space character. **************************************/ 
WinSendMsg /* Send space character message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character message. */ 

MPFR0M2SHORT (KC_CHAR, 1), /* Character key. */ 

MPFROM2SHORT (* *,0)); /* Space character. */ 

/*** Restore cursor position (printing space advanced it!). ********/ 
WinSendMsg /* Send left-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character received message. */ 

MPFR0M2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. V 

MPFROM2SHORT (0, VK__LEFT) ) ; /* Left-arrow code. */ 

} /* end overwrite mode */ 

/*** signal system that key was processed. *******************************/ 
return TRUE? 

} /* end '\b' */ 

/*** process a Tab key by sending equivalent number of space characters. *****/ 

if (CHARMSG(&msg)->chr == '\t■) 

{ 

Col = 5 - Cursored % 5; 
while (Col--) 
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WinSendMsg /* Send space character message to self. */ 


(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character message. */ 

MPFR0M2SHORT (KC_CHAR, 1), /* Character key. */ 

MPFR0M2SHORT (' ',0)); /* Space character. */ 

return TRUE; 


} /* end ! \t' */ 

/*** Process Enter key. ******************************************************/ 

if (CHARMSG(&msg)->chr == '\r') 

{ 

/*** if in insert mode, insert a new line into buffer. ******************/ 

if (Insert) 

{ 

/*** insert the line into file buffer. *****************************/ 
InsertLine (CursorLine, CursorCol); 

/*** Adjust 'TopLineMax' and scroll bar range for new file length. */ 
TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 


WinSendMsg /* Adjust scroll bar range. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFROM2SHORT (TopLine, 0) , /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable only if scroll possible. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

TopLineMax ? 1 : 0); /* Enable only if max. 1=0. */ 


/*** invalidate 'CursorLine' and all lines below. ******************/ 

Rect.xLeft = 0; 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 
Rect.yBottom = 0; 

WinlnvalidateRect 
(hwnd, 

&Rect, 

FALSE); 

/*** Force update of client window. ********************************/ 
WinUpdateWindow (hwnd); 

} /* end insert mode */ 

/*** Move cursor down one line. *****************************************/ 
WinSendMsg /* Move cursor down. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), 

MPFROM2SHORT (0, VK_DOWN)); 
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/*** Adjust 1 LastCursorLine 1 if in insert mode, 
if (Insert) 

LastCursorLine = CursorLine; 




/*** 


Move cursor to beginning of line. 
WinSendMsg /* 

(hwnd, /* 

WM_CHAR, /* 

MPFR0M2SHORT (KC_VIRTUALKEY, 
MPFR0M2SHORT (0, VK_H0ME)); 
return TRUE; 




Send Home key message to self. */ 

Client window handle. */ 

Character received message. */ 

1), /* Virtual key. */ 

/* Home key code. */ 


} /* end '\r 7 */ 


/*** Process all remaining character keys. ***********************************/ 

/*** insert key into file buffer. ********************************************/ 
if (UnsertChar 

(CursorLine, 

CHARMSG(&msg)->chr, 

CursorCol, 

Insert)) 

/*** Beep if insertion failed (max buffer length exceeded). *************/ 
WinAlarrn (HWND_DESKTOP, WA_ERR0R); 
return TRUE; 

} 

/*** invalidate window from cursor position to end of line (or window). ******/ 

Rect.xLeft = (CursorCol - FirstCol) * xChar; * . 

Rect.xRight = min ((GetLineLength (CursorLine) - FirstCol) * xChar, xWm) ; 
Rect.yBottom = yWin - (CursorLine - TopLine +1) * yCharTot; 

Rect.yTop = Rect.yBottom + yCharTot; 


WinlnvalidateRect 
(hwnd , 

&Rect, 

FALSE); 


/* Invalidate section to be modified. */ 
/* Handle of client window. ... */ 
/* Rectangle to be added to invalid region. */ 
/* Don't include descendants w/ WS_CLIPCHILDREN*/ 


WinUpdateWindow (hwnd); /* Force updating of client window. */ 

/*** Move the cursor right one column. ***************************************/ 


WinSendMsg /* Send right-key message to self, 

(hwnd, /* Client window handle. 

WM CHAR, /* Character message. 

MPFR0M2SHORT (KC_VIRTUALKEY,1) , /* ^P 1 • 

MPFR0M2SHORT (0, VK_RIGHT)) ; /* m P 2 * 

return TRUE; 

} /* end Character */ 


*/ 

*/ 

*/ 

*/ 

*/ 
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MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


HPS HPresSpace; 
FONTMETRICS Metrics; 
LONG NumberStructs = l; 


/* Presentation space handle. 

/* Structure to hold font dimensions. 

/* Number of structures from GpiQueryFonts. 


*/ 

*/ 

*/ 


GpiLoadFonts /* Load Courier font. */ 

(HAncBlk, /* Anchor block handle. */ 

"\\0S2\\DLL\\C0URIER.FON"); /* Full path name of font file. */ 

HPresSpace = WinGetPS (hwnd); 


GpiQueryFonts /* Obtain information on Courier font. 

(HPresSpace, /* Handle to presentation space. 

QF_PRIVATE, /* Enumerate private fonts. 

"Courier", /* Font face name. 

&NumberStructs, /* Number of FONTMETRICS structures returned 

(long)sizeof (FONTMETRICS),/* Length of structure for EACH font. 
^Metrics); /* Address of FONTMETRICS structure(s). 


V 

*/ 

V 
*/ 
*/ 
*/ 
*/ 


xChar 

yCharTot 

yCharDesc 


(SHORT)Metrics.lAveCharWidth; 

(SHORT)Metrics.IMaxBaselineExt; 
(SHORT)Metrics.IMaxDescender; 


FontAttributes.usRecordLength = sizeof (FontAttributes); 
FontAttributes.fsSelection = Metrics.fsSelection; 
FontAttributes.IMatch = Metrics.IMatch; 
strcpy (FontAttributes.szFacename,Metrics.szFacename); 
FontAttributes.idRegistry = Metrics.idRegistry; 
FontAttributes.usCodePage = Metrics.usCodePage; 
FontAttributes.IMaxBaselineExt = Metrics.IMaxBaselineExt; 
FontAttributes.lAveCharWidth = Metrics.lAveCharWidth; 
FontAttributes.fsType = FATTR_TYPE_FIXED; 

FontAttributes.fsFontUse = 0; 

WinReleasePS (HPresSpace); 


HHScroll = WinWindowFromID 

(WinQueryWindow (hwnd, QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 

FID_HORZSCROLL); /* Identifier for vertical scroll bar. */ 

HVScroll = WinWindowFromID 

(WinQueryWindow (hwnd, QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 

FID_VERTSCROLL); /* Identifier for vertical scroll bar. */ 


return FALSE; 


} /* end Create */ 


MRESULT EXPENTRY HScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

SHORT Delta; /* Amount to scroll. */ 
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/*** Determine amount to scroll. 




switch (SH0RT2 FROMMP (mp2)) 

{ 

case SB_LINELEFT: 

Delta = -1; 
break; 

case SB_LINERIGHT: 

Delta = 1; 
break; 

case SB_PAGELEFT: 

Delta = -6; 
break; 

case SB_PAGERIGHT: 

Delta = 6; 
break; 

case SB_SLIDERPOSITION: 

Delta = SHORT1FROMMP (mp2) - FirstCol; 

break; 
default: 

Delta = 0; 
break; 

Deltamax (-FirstCol, min (Delta,FirstColMax - FirstCol)); 


if (Delta) 

{ 

FirstCol += Delta; 


/*** Update cursor column. 
CursorCol += Delta; 




/*** Hide the cursor. *************** 
WinShowCursor 


(hwnd, 

/* 

FALSE); 

/* 

WinScrollWindow 

/* 

(hwnd, 

/* 

-Delta * xChar, 

/* 

0, 

/* 

0, 

/* 

0, 

/* 

o, 

/* 

0, 

/* 

SW_INVALIDATERGN); 

/* 

WinUpdateWindow 

/* 

(hwnd); 

/* 

WinSendMsg 

/* 

(HHScroll, 

/* 

SBM SETPOS, 

/* 


MPFROM2SHORT (FirstCol,0), 
0 ) ; 




Client window handle. */ 

Hide it! */ 

Scroll the window data. */ 

Handle of client window. */ 

Horizontal scroll amount. */ 

Vertical scroll amount. */ 

Must be 0. */ 

Must be 0. V 

Must be 0. */ 

Must be 0. */ 

Invalidate "exposed” region. */ 

Force updating of client window. */ 
Handle of client window. */ 


Handle to horizontal scroll bar. */ 
Set position of slider. */ 

/* Current position. */ 

/* Second parameter: n/a. */ 
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/*** Restore cursor to correct position. ********************************/ 

WinCreateCursor /* Set position of cursor. */ 

(hwnd, /* client window handle. */ 

(Cursored - FirstCol) * xChar, /* x position of cursor. */ 

yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 
°f /* x size of cursor: n/a. */ 

/* y size of cursor: n/a. */ 

CURSOR_SETPOS, /* Option to set position only. */ 

NULL ) ; /* Clipping rectangle: n/a */ 

/*** Show the cursor again. *********************************************/ 

WinShowCursor / 

(hwnd, /* client window handle. */ 

TRUE); /* show iti */ 

) /* end if (Delta) */ 
return FALSE; 


} /* end HScroll */ 


MRESULT 


EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


register int Line; 
HPS HPresSpace; 
RECTL Rect; 

SHORT StartLine; 
SHORT StopLine; 
POINTL Start; 

SHORT LineLength; 


/* Loop counter. 

/* Presentation space handle. 

/* Holds coordinates of rectangle. 

/* First file line to paint. 

/* Last line to paint. 

/* Starting position to print string. 
/* Length of each line displayed. 


HPresSpace = WinBeginPaint 


(hwnd, 

0 , 

&Rect); 

GpiCreateLogFont 
(HPresSpace, 
(PSTR8)NULL, 

I D__COURIER, 
&FontAttributes); 

GpiSetCharSet 

(HPresSpace, 
ID_COURIER); 

WinFillRect 

(HPresSpace, 

&Rect, 

CLR_WHITE); 

GpiSetColor 

(HPresSpace, 
CLR_BLACK); 


/* Window handle. */ 
/* Handle of PS to have clipping region set. */ 
/* Address of struct, to set to invalid region.*/ 

/* Create a logical font for presentation space*/ 
/* Presentation space handle. */ 
/* Logical font name: none. */ 
/* Local font ID: define a constant. */ 
/* Struct, specifying font from GpiQueryFonts. */ 

/* Make logical font the current character set.*/ 
/* Presentation space handle. */ 
/* Local font ID. */ 


/* Presentation space handle. 

/* Structure containing window coordinates. 
/* Color to use (white). 


/* Presentation space handle. 
/* Color to use: black. 
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StartLine = TopLine + (yWin - (SHORT)Rect.yTop) / yCharTot; 

StopLine = min (LastLine, TopLine + (yWin - (SHORT) Rect.yBottom) 

/ yCharTot); 

Start.y = yWin - yCharTot * (StartLine - TopLine + 1) + yCharDesc; 
Start.x = xChar * (-FirstCol)? 

for (Line = StartLine; Line <= StopLine; ++Line, Start.y -= yCharTot) 


if ((LineLength = GetLineLength (Line)) == 0) 


continue; 
GpiCharStringAt 

(HPresSpace, 

&Start, 

(LONG)LineLength, 
GetLineAddr (Line) 


/* Prints string at given position. */ 
/* Presentation space handle. */ 
/* Structure containing starting position.*/ 
/* Number of characters to print. */ 
;/* Address of line. */ 


} 


WinEndPaint (HPresSpace); 


return FALSE; 

} /* end Paint */ 


MRESULT 

{ 

/*** If 
if 


mpx, 


EXPENTRY SetFocus (HWND hwnd, USHORT msg, 

client window is RECEIVING focus, create cursor. 
(LONGFROMMP (mp 2)) 

{ 






WinCreateCursor /* Create a new cursor. 

(hwnd, /* Client window handle. 

(Cursored - FirstCol) * xChar, /* x position of cursor. 
yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. 

0 /* x size of cursor: nominal border 

yCharTot, /* y size of cursor. 

CURS0R_SOLID | /* Solid cursor. 

CURSOR_FLASH, /* Blinking cursor. 


*/ 

V 

*/ 

V 

V 

*/ 

V 

V 


null) ; 


/* Clipping rectangle: entire window.*/ 


/*** 


/*** Make the cursor visible. 
WinShowCursor 
(hwnd, 

TRUE); 


/* Client window handle. */ 

/* Show it! */ 


If client window is LOSING focus, 
else 

WinDestroyCursor (hwnd); 


destroy the cursor. *******************/ 


return FALSE; 

} /* end SetFocus */ 


MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

( 

int Update = 0; 

yWin = SH0RT2 FROMMP (mp2) ; 
xWin = SHORT1FROMMP (mp2); 
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/*** Scroll window if necessary so that cursor position is visible. **** 

if (CursorLine >= TopLine + yWin / yCharTot) 

TopLine = CursorLine - yWin / yCharTot + 1; 

Update =1; 

} 

if (CursorCol > FirstCol + xWin / xChar - 1) 

FirstCol = CursorCol - xWin / xChar + l; 

Update = 1; 


if (Update) 

WinlnvalidateRect 

(hwnd, 

0 , 

FALSE); 


/* Client window handle. */ 
/* Rectangle; 0 means whole window. */ 
/* Do not automatically include children. */ 


/*** if client has focus, must RE-CREATE the cursor for new si 


ze. ************/ 


if (hwnd == WinQueryFocus /* Does client have focus? */ 

(HWND_DESKTOP, /* Must give desktop handle. */ 

FALSE)) /* Do not lock window. */ 

{ 

/*** Destroy existing cursor. *******************************************/ 
WinDestroyCursor (hwnd); 


/*** create new cursor. *************************************************/ 
WinCreateCursor /* Create a new cursor. */ 

(hwnd, /* client window handle. */ 

(CursorCol - FirstCol) * xChar, /* x position of cursor. */ 
yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 
°/ /* x size of cursor; nominal border. */ 

yCharTot, /* y size of cursor. */ 

CURSOR_SOLID | /* Solid cursor. */ 

CURSOR_FLASH, /* Flashing cursor. */ 

NULL); /* Clipping rectangle; entire window.*/ 

/*** Display the cursor. ************************************************/ 
WinShowCursor 

(hwnd, /* Client window handle. */ 

TRUE); /* Show it! */ 


TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

TopLine = min (TopLine,TopLineMax); 

WinSendMsg /* Adjust range/position of slider. */ 

(HVScroll, /* Recipient handle; vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0) , /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable scroll bar if scrolling is possible. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

TopLineMax ? TRUE : FALSE); /* Enable only if max. != 0. */ 


Figure 624: 

The source code file for the example program (continued) 







FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 

FirstCol = min (FirstCol, FirstColMax); 

WinSendMsg /* Adjust range/position of slider. */ 

(HHScroll, /* Recipient handle: horizontal scroll bar*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (FirstCol, 0), /* Position. */ 

MPFR0M2SHORT (0, FirstColMax)); /* Range. */ 

return FALSE; 

} /* end Size */ 

MRESULT EXPENTRY VirtKey (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

RECTL Rect; /* Holds coordinates of rectangle. */ 

SHORT NewFirstCol; /* Temporary storage for new first column pos. */ 

SHORT NewCursorCol; /* Temporary storage for new cursor column. */ 

int Update; /* Flag indicating window update needed. */ 

/*** Branch according to virtual key code. ***********************************/ 

switch (CHARMSG (&msg)->vkey) 

/*** Process up-arrow key. **********************************************/ 
case VK_UP: 

/*** if cursor at top of window, scroll up. ************************/ 
if (CursorLine == TopLine) 

WinSendMsg /* Scroll window one line up. */ 

(hwnd, 

WM_V S CRO LL, 

0L, 

MPFROM2SHORT (0,S B_LINEUP)) ; 
return TRUE; 

/*** if cursor NOT at top, simply adjust ’CursorLine*. *************/ 
else 

—CursorLine; 
break; 

/*** Process down-arrow key. ********************************************/ 
case VK_D0WN: 

/*** if cursor at end of file, simply return. **********************/ 
if (CursorLine == LastLine) 
return TRUE; 

/*•** If cursor is in bottom line of window, scroll down. ***********/ 
else if (CursorLine == TopLine + yWin / yCharTot - 1) 

{ 

WinSendMsg 
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(hwnd, 

WM_VSCROLL, 

OL, 

MPFROM2 SHORT (0,SBLINEDOWN)) ; 
return TRUE; 

} , 

/*** otherwise, simply adjust 'CursorLine'. ************************/ 
else 

++CursorLine; 
break; 

/*** Process left-arrow key. ********************************************/ 
case VK_LEFT: 

/*** if cursor is at left of window, scroll left. ******************/ 
if (CursorCol == FirstCol) 

{ 

WinSendMsg 

(hwnd, 

WM_HSCROLL, 

OL, 

MPFR0M2 SHORT (0,SB_LINELEFT)) ; 
return TRUE; 

} > 

/*** Otherwise, simple adjust 'CursorCol 1 . *************************/ 
else 

—CursorCol; 
break; 

/*** Process right-arrow key. *******************************************/ 
case VK_RIGHT: 

/*** if cursor is at right of window, scroll to right. *************/ 
if (CursorCol == FirstCol + xWin / xChar - 1) 

{ 

WinSendMsg 

(hwnd, 

WM_HSCROLL, 

OL, 

MPFROM2 SHORT (0,SB_LINERIGHT) ) ; 
return TRUE; 

} 

/*** otherwise, simply adjust 'CursorCol'. *************************/ 
else 

++CursorCol; 
break; 

/*** Process Page Up key. ***********************************************/ 
case VK_PAGEUP: 

WinSendMsg /* Send scroll page-up message to self. */ 

(hwnd, 

WM_VSCROLL, 

OL, 

MPFR0M2 SHORT (0,SB_PAGEUP) ) ; 
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return TRUE ; 


/*** Process Page Down key. *********************************************/ 
ca.se VK_PAGEDOWN: 

WinSendMsg /* Send scroll page-down message to self. */ 

(hwnd, 

WM_VSCROLL, 

OL, 

MPFR0M2 SHORT (0,S B_PAGE DOWN)) ; 
return TRUE; 

/*** Process Home key. **************************************************/ 
case VK__HOME: 

/*** Scroll if beginnings of lines not visible. ********************/ 
if (FirstCol != 0) 

WinSendMsg /* Send scroll to absolute position */ 

/* message to self. */ 

(hwnd, 

WM_HSCROLL, 

OL, 

MPFROM2 SHORT (0,SB_SLIDERPOSITION)) ; 


Cursored = 0 ; 
break; 

/*** Process End key.. ***************************************************/ 

case VKJEND: 

/*** set temporary cursor position to end of line. *****************/ 
NewCursorCol = (int)GetLineLength (CursorLine); 

/*** Clear update flag. ********************************************/ 
Update = 0; 

/*•** End of line to right of portion visible in window. ************/ 
if (NewCursorCol > FirstCol + xWin / xChar - 1) 

( 

NewFirstCol = NewCursorCol - xWin / xChar + 1; 

Update = 1; 

/*** End of line to left of portion visible in window. **************/ 
else if (NewCursorCol < FirstCol) 

( 

NewFirstCol = NewCursorCol; 

Update = 1; 

/*** Scroll window if end of line not visible. *********************/ 
if (Update) 

WinSendMsg 

(hwnd, 

WM_HSCROLL, 
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OL, 

MPFROM2 SHORT (NewFirstCol, 

SB_SLIDERPOSITION)); 

/*** Set permanent cursor column position. *************************/ 
CursorCol = NewCursorCol; 
break; 

/*** Process Del key. ***************************************************/ 
case VK_DELETE: 

/*** if modifying a new line, must place line in temporary buffer. */ 
if (LastCursorLine != CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

} 

/*** Delete character from file buffer. ****************************/ 
if (DeleteChar (CursorLine,CursorCol)) 

{ 

/*** If deletion successful, invalidate window from cursor 

position to end of line. *********************************/ 

Rect.xLeft = (CursorCol - FirstCol) * xChar; 

Rect.xRight = min 

((GetLineLength (CursorLine) + 1 - FirstCol) * xChar, 
xWin); 

Rect.yBottom = yWin - (CursorLine - TopLine +1) * yCharTot; 
Rect.yTop = Rect.yBottom + yCharTot; 

WinlnvalidateRect /* Invalidate region to be updated. */ 
(hwnd, 

&Rect, 

FALSE); 

WinUpdateWindow (hwnd); /* Force client window update. */ 

} 

return TRUE; 

/*** process Ins key by toggling 'Insert' flag. *************************/ 
case VK_INSERT: 

Insert ~= 1; 
return TRUE; 

/*** Process F9 key: delete line containing cursor. ********************/ 
case VK_F9: 

/*** If modifying a new line, must place line in temporary buffer. */ 
if (LastCursorLine != CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

} 
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/*** Adjust 'TopLineMax' and scroll bar range for new file length. */ 
TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

WinSendMsg 

(HVScroll, /* Recipient handle. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFROM2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow 

(HVScroll, /* Recipient handle. */ 


TopLineMax ? 1 : 0); /* Enable only if max.!= 0*/ 

/*** invalidate 'CursorLine' and all lines below. ******************/ 


Rect.xLeft = 0; 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 

Rect.yBottom = 0; 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* No descendants w/ WS_CLIPCHILDREN. */ 

WinUpdateWindow (hwnd); /* Force updating of client window. */ 


return TRUE; 

/*** For all other keys, return FALSE indicating key not processed. *****/ 
default: 

return FALSE; 

} /* end virtual key switch */ 

/*** Update cursor position for all cases above that altered 'CursorLine' or 
'Cursored'. ****************************************************************V 


WinCreateCursor /* Set position of cursor. */ 

(hwnd, /* Client window handle. */ 

(CursorCol - FirstCol) * xChar, /* x position of cursor. */ 

yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 

0, /* x size of cursor: n/a. */ 

0, /* y size of cursor: n/a. */ 

CURSOR_SETPOS, /* Option to set position only. */ 

NULL); /* Clipping rectangle: n/a */ 


return TRUE; 

} /* end VirtKey */ 

MRESULT EXPENTRY VScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

SHORT Delta; /* Amount to scroll. */ 
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/*** Determine amount to scroll. *********************************************y 

switch (SH0RT2FR0MMP (mp2)) /* Switch on code from scroll bar. */ 

case SB_LINEUP: 

Delta = -1; 
break; 

case SB_LINEDOWN: 

Delta = 1; 
break; 

case SB_PAGEUP: 

Delta = -yWin / yCharTot; 
break; 

case SB_PAGEDOWN: 

Delta = yWin / yCharTot; 
break; 

case SB_SLIDERPOSITION; 

Delta = SH0RT1FR0MMP (mp2) - TopLine; 
break; 
default: 

Delta = 0; 
break; 

} 

Delta = max (-TopLine, min (Delta,TopLineMax - TopLine)); 

if (Delta) 

{ 

TopLine += Delta; 

/*** Update cursor line. ************************************************/ 
CursorLine += Delta; 


/*** Hide the cursor. 

WinShowCursor 
(hwnd, 

FALSE); 

WinscrollWindow 
(hwnd, 

0 , 

yCharTot * Delta, 

0 , 

0 , 

0 , 

0 , 

SW_INVALIDATERGN); 

WinUpdateWindow 
(hwnd); 

WinSendMsg 

(HVScroll, 

SBM_SETPOS, 

MPFROM2 SHORT (TopLine,0),/* 


Client window handle. */ 

Hide it! */ 


Handle of client window. */ 
Horizontal scroll amount. */ 
Vertical scroll amount. */ 
Must be 0. */ 
Must be 0. */ 
Must be 0. */ 
Must be 0. */ 
Invalidate "exposed" region. */ 


Handle of client window. */ 


Handle to vertical scroll bar. */ 
Set position of slider. */ 
Current position. */ 


/* 
/* 


/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 
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0); /* Second parameter n/a. */ 

/*** Restore cursor to correct position. ********************************/ 

WinCreateCursor /* Set position of cursor. */ 

(hwnd, /* Client window handle. */ 

(CursorCol - FirstCol) * xChar, /* x position of cursor. */ 

yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 
0, /* x size of cursor: n/a. */ 

0, /* y size of cursor: n/a. */ 

CURSOR_SETPOS, /* Option to set position only. */ 

NULL); /* Clipping rectangle: n/a */ 

/*** Show the cursor again. *********************************************/ 
WinShowCursor 

(hwnd, /* Client window handle. */ 

TRUE)? /* Show it! */ 


} /* end if (Delta) */ 
return FALSE; 

} /* end VScroll */ 

/*** Buffer-management module ************************************************/ 
#define MAXLINES 4096 /* Maximum number of lines in file buffer.*/ 


static struct /* Stores information on each line. */ 

{ 

PCH LineAddress; /* Far address of block containing line. */ 

unsigned char LineLength; /* Length of line (includes \n and \0). */ 

} 

LineTable [MAXLINES]; 

static char LineBuffer [LINEBUFSIZ]; /* Temporary line buffer. */ 

static unsigned LineSelector; /* Selector for 'LineBuffer'. */ 

static unsigned LineOffset; /* Offset for 'LineBuffer'. */ 

static SEL HeapSelector; /* Selector of heap segment. */ 

void Buflnit (void) /* Initializes the buffer-management module. */ 

{ 

PCH FarPtr; 


FarPtr = (char far *)LineBuffer; 
LineSelector = SELECTOROF (FarPtr); 
LineOffset = OFFSETOF (FarPtr); 

} /* end Buflnit */ 


int DeleteChar /* Deletes a character from 'LineBuffer'. */ 

(SHORT Line, /* Line containing character to be deleted. */ 
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SHORT Column) /* Number of character to be deleted. */ 

/* 

This function deletes the indicated character from 1 LineBuffer 1 . It 
returns TRUE if the buffer was modified, and FALSE if no action took 
place (i.e., the specified character was beyond the visible end of the 
line). 

*/ 

{ 

/*** Return FALSE if character is beyond visible length of line. *************/ 
if (LineTable [Line].LineLength <3 | | 

Column > LineTable [Line].LineLength - 3) 
return FALSE; 

/*** Move all characters beyond deleted character one place left. ************/ 
memmove 

j (LineBuffer + Column, /* Target. */ 

LineBuffer + Column +1, /* Source. */ 

LineTable [Line].LineLength - Column - 1); /* Number of bytes. */ 

/*** Adjust line length. ****************************************************V 
--LineTable [Line].LineLength; 

return TRUE; 

} /* end DeleteChar */ 


void DeleteLine (SHORT Line) 

/* 

Deletes the specified line ('Line', which must be the line currently 
containing the cursor) from the file buffer. 

V 

( 

/*** if line to be deleted is the last file line, merely truncate it. ********/ 

if (Line == LastLine) ! 

( 

LineBuffer [0] = 1 \n'; 

LineBuffer [1] = '\0'; 

LineTable [Line].LineLength = 2; 

} 

else 

/*** Place the following line into 'LineBuffer'. ************************/ 
GetTempBuf (Line + 1); 

/*** Move all LineTable elements beyond deleted line down one element. **/ 
memmove 

(ScLineTable [Line], /* Target. V 

&LineTable [Line + 1], /* Source. */ 

(LastLine - Line) * sizeof (LineTable [0])); /* Number bytes. */ 

/*** Adjust 'LastLine'. **************************************************/ 
--LastLine; 

} 
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} /* end DeleteLine */ 


char *ErrorMessage (int ErrorNumber) 

/* 

Returns a string that describes the error code given by 'ErrorNumber 

V 

{ 

static char *MessageTable [] = 

{ 

"no error", 

"file open failure", 

"file too large", 

"maximum lines exceeded", 

"heap memory allocation failed", 

"unidentified error" 

) ? 

if (ErrorNumber >= sizeof (MessageTable) / sizeof (char *)) 

ErrorNumber = sizeof (MessageTable) / sizeof (char *) - 1; 

return MessageTable [ErrorNumber]; 

} /* end ErrorMessage */ 


PCH GetLineAddr (int Line) 

/* 

Returns the address of the file buffer line specified by 'Line'. 

*/ 

{ 

if (Line < 0 || Line > LastLine) 
return NULL; 

else 

return LineTable [Line].LineAddress; 

} /* end GetLineAddr */ 


SHORT GetLineLength (int Line) 

/* 

Returns the length of the file buffer line specified by 'Line'. 

*/ 

{ 

if (Line < 0 || Line > LastLine) 
return 0; 

else 

return LineTable [Line].LineLength - 2; 

} /* end GetLineLength */ 


void GetTempBuf /* Places specified line into 'LineBuffer'. 

(int Line) /* Number of line. 

/* 


Figure 6.24: 

The source code file for the example program (continued) 




• 292 Programmer's Guide to the OS/2 Presentation Manager 


This function: 

o Copies the string in the specified line into 'LineBuffer' 
o Frees the block formerly holding the string 
o Adjusts the address in 'LineTable' 

*/ 

{ 

/*** Copy string into 'LineBuffer'. ******************************************/ 
movedata /* Intersegment block copy.*/ 


(SELECTOROF (LineTable[Line].LineAddress), /* Source segment. */ 

OFFSETOF (LineTable[Line].LineAddress), /* Source offset. */ 

Lineselector, /* Target segment. */ 

LineOffset, /* Target offset. */ 

LineTable [Line].LineLength); /* Bytes to copy. */ 

/*** Release block formerly holding line. ************************************/ 
if (WinFreeMem 

(HHeap, /* Handle of heap from 'WinCreateHeap’. */ 

(BYTE NEAR *)OFFSETOF (LineTable [Line].LineAddress), /* Offset. */ 

LineTable [Line].LineLength) /* Length of block to free. */ 

! = NULL) 

{ 

sprintf (Message,"managing heap; line %d",_LINE_); 

ErrorQuit (Message); 

} 


/*** place new address into 'LineTable'. *************************************/ 
LineTable [Line].LineAddress = MAKEP (LineSelector,LineOffset); 

} /* end GetTempBuf */ 


int 

InsertChar 

/* 

Inserts character into 'LineBuffer'. 

*/ 


(SHORT Line, 

/* 

Number of line for insertion. 

*/ 


USHORT Character, 

/* 

Character to insert. 

*/ 


SHORT Column, 

/* 

Column position of character. 

*/ 


int Insert) 

/* 

Flag indicating overwrite mode. 

V 


unsigned char LineLength 




/*** 

Obtain the length of the 

line. ******************************************/ 


LineLength = LineTable [Line].LineLength; 



/*** jf line would exceed maximum line length, return without inserting. *****/ 
if (Column > LINEBUFSIZ -3 || LineLength >= LINEBUFSIZ && Insert) 

return FALSE; 


/*** jf column is at end of line (common case), use fast routine to insert. **/ 
else if (Column == LineLength - 2) 

/*** Copy '\n' and '\0' to new position. ********************************/ 
LineBuffer [Column + 2] = LineBuffer [Column + 1]; 

LineBuffer [Column + 1] = LineBuffer [Column]; 

/*** write the character. ***********************************************/ 
LineBuffer [Column] = (char)Character; 
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/*** if column is BEYOND end of line, must pad line with spaces. *************/ 
else if (Column > LineLength - 2) 

( 

/*** Copy 1 \n 1 and ' \0' to new position. ********************************/ 
LineBuffer [Column + 2] = LineBuffer [LineLength - 1]; 

LineBuffer [Column + 1] = LineBuffer [LineLength - 2]; 

/*** Fill line with spaces. *********************************************/ 
memset 


(LineBuffer + LineLength - 2, 

/* 

Destination. 

V 

i i 

/ 

/* 

Character 

to fill with. 

V 

Column - LineLength + 2) ; 

/* 

Number of 

repetitions. 

*/ 


/*** write character. ***************************************************/ 
LineBuffer [Column] = (char)Character; 

/*** Adjust line length. ************************************************/ 
LineTable [Line].LineLength = (unsigned char)Column + 3; 
return TRUE; 

} 

/*** Otherwise, must insert character in middle of line. *********************/ 
else 

{ 

/*** if insert mode is active, move all characters right of insertion 

point one space to the right. **************************************/ 
if (Insert) 

{ 


memmove 


/* 

Move block. 

*/ 

(LineBuffer + 

Column + 1, 

/* 

Target. 

V 

LineBuffer + 

Column, 

/* 

Source. 

V 

LineLength 

Column); 

/* 

Number of bytes. 

*/ 


/*** Adjust line length. *******************************************/ 
++LineTable [Line].LineLength; 

} 

/*** write character. ***************************************************/ 
LineBuffer [Column] = (char)Character; 
return TRUE; 

} 

} /* end InsertChar */ 


void InsertLine (SHORT Line, SHORT Column) 

/* 

Inserts a new line into the file buffer, immediately before character 
given by 'Column', within the line given by 'Line'. 

V 

{ 


© Figure 6.24: 

The source code file for the example program (continued) 




Programmer's Guide to the OS/2 Presentation Manager 


NPCH HeapOffset; /* Holds 16-bit heap offset. */ 

PCH HeapPointer; /* Holds far pointer to heap base. */ 

/*** Fatal error if maximum lines reached. ***********************************/ 
if (++LastLine >= MAXLINES) 

( 

sprintf (Message,"maximum lines reached; line %d", _LINE_); 

ErrorQuit (Message); 

} 

/*** Adjust 'Column* to maximum position in line. ****************************/ 
if (Column > LineTable [Line].LineLength - 2) 

Column = LineTable [Line].LineLength - 2; 

/*** Allocate a block for characters in line before 'Column*. ****************/ 
HeapOffset = WinAllocMem 
(HHeap, 

Column + 2); 
if (HeapOffset == NULL) 

{ 

sprintf (Message,"out of heap memory; line %d", _LINE_); 

ErrorQuit (Message); 

) 


/*** copy characters before 'Column' 

1 into new block. *************************/ 

movedata 

/* 

Intersegment block copy. 

*/ 

(Lineselector, 

/* 

Source: 

selector of 'LineBuffer'. 

*/ 

LineOffset, 

/* 

Source: 

offset of 'LineBuffer'. 

*/ 

HeapSelector, 

/* 

Target: 

selector of heap. 

*/ 

(unsigned)HeapOffset, 

/* 

Target: 

: offset of new block. 

V 

Column); 

/* 

Number 

of characters to copy. 

V 


/*** Construct a far pointer to new block in heap. ***************************/ 
HeapPointer = MAKEP (HeapSelector,HeapOffset); 

/*** write newline and null to end of new line in heap. **********************/ 
*(HeapPointer + Column) = '\n'; 

*(HeapPointer + Column + 1) = 1 \0'; 

/*** Move character number 'Column' and all following characters to beginning 

of 'LineBuffer'. ********************************************************/ 


memmove 

/* 

Intrasegment block 

copy.*/ 

(LineBuffer, 

/* 

Target address. 

V 

LineBuffer + Column, 

/* 

Source address. 

V 

LineTable [Line].LineLength - Column); 

/* 

Bytes to move. 

*/ 


/*** Adjust line length. *****************************************************/ 
LineTable [Line].LineLength -= (unsigned char)Column; 

/*** Move all members of 'LineTable' one position toward end of table. *******/ 
memmove 

(&LineTable [Line +1], /* Target. */ 

SLineTable [Line], /* Source. V 

(LastLine - Line) * sizeof (LineTable [0])); /* Bytes to move. */ 
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/*** Assign address of new heap block to 'LineTable'. ************************/ 
LineTable [Line].LineAddress = HeapPointer; 

LineTable [Line].LineLength = (unsigned char)(Column + 2); 

} /* end InsertLine */ 


int JoinLine (SHORT Line) 

/* 

Combines the line in the file buffer given by 'Line' with the previous 
line. 

V 

{ 

/*** Return if 'Line' is the first in the file (no previous line). ***********/ 
if (Line == 0) 

return FALSE; 

/*** Return if combined length would exceed maximum line length. *************/ 
if (LineTable [Line].LineLength + LineTable [Line - 1].LineLength - 2 > 
LINEBUFSIZ) 
return FALSE; 

/*** Move existing characters in 'LineBuffer' to right to make room for the 

characters from previous line. ******************************************/ 


memmove 

(LineBuffer + LineTable [Line - 1].LineLength - 2, /* Target. */ 
LineBuffer, /* Source. */ 

LineTable [Line].LineLength); /* Number of bytes. */ 

/*** Move the characters from previous line to beginning of 'LineBuffer'. ****/ 
movedata 

(SELECTOROF (LineTable [Line - 1].LineAddress), /* Source. */ 

OFFSETOF (LineTable [Line - 1].LineAddress), /* Source. */ 

LineSelector, /* Target. */ 

LineOffset, /* Target. */ 

LineTable [Line - 1].LineLength -2); /* Bytes to copy.*/ 

/*** Adjust line length for added characters. ********************************/ 
LineTable [Line].LineLength += LineTable [Line - 1].LineLength - 2; 

/*** Free block used by previous line. ***************************************/ 
if (WinFreeMem 

(HHeap, /* Handle of heap from 'WinCreateHeap'. */ 

(BYTE NEAR *)OFFSETOF (LineTable [Line-1].LineAddress), /* Offset. */ 
LineTable [Line-1].LineLength) /* Length of block to free. */ 

! = NULL) 

{ 

sprintf (Message,"managing heap; line %d",_LINE_); 

ErrorQuit (Message); 

} 


/*** Move all 'LineTable' members above and including 'Line' down one place. */ 
memmove 

(&LineTable [Line -1], /* Destination. */ 

SLineTable [Line], /* Source. */ 
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(LastLine - Line + 1) * sizeof (LineTable [0])); /* Bytes to move.*/ 

/*** Adjust 'LastLine'. ******************************************************/ 
—LastLine; 

return TRUE; 

} /* end JoinLine */ 

void NewFile (void) 

/* 

Initializes the file buffer for a new empty file. 

*/ 

{ 

PCH FarPtr; /* Temporary far character pointer. */ 

/*** Initialize 'LineBuffer'. ************************************************/ 
LineBuffer [0] = '\n'; 

LineBuffer [1] = '\0'; 

/*** Initialize 'LineTable' for first (and only) line. ***********************/ 
LineTable [0].LineAddress = MAKEP (LineSelector, LineOffset); 

LineTable [0].LineLength = 2; 

/*** Initialize 'LastLine'. **************************************************/ 
LastLine = 0; 

/*** create a heap to hold data added to file. *******************************/ 
HHeap = WinCreateHeap 


(0, 

/* 

Segment 

address: 0 means allocate 

new segment. 

*/ 

4096, 

/* 

Initial 

heap size. 


V 

o, 

/* 

Minimum 

increase size: 0 means use 

default. 

V 

o, 

/* 

Minimum 

# of dedicated free lists: 

none. 

*/ 

o, 

/* 

Maximum 

# of dedicated free lists: 

none. 

V 

HM MOVEABLE); 

/* 

Options: 

: support movable objects. 


*/ 


/*** Obtain selector address of heap. ****************************************/ 
FarPtr = WinLockHeap (HHeap); 

HeapSelector = SELECTOROF (FarPtr); 

} /* end NewFile */ 


int ReadFile /* Reads file into editor. */ 

(char *FileName) /* Name of file. */ 

FILE *PtrFile; /* File stream pointer. */ 

long FileLength; /* Size of file. */ 

USHORT HeapSize; /* Size of allocated heap. */ 

NPCH HeapOffset; /* Offset of blocks within heap. */ 

unsigned char LineLength; /* Length of lines. */ 

PCH FarPtr; /* Temporary far pointer. */ 

if ((PtrFile = fopen (FileName,"r")) == NULL) /* Open file. */ 
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return (ERROPEN); 


/* Get length of file. */ 

if ((FileLength = filelength (fileno (PtrFile))) == -1) 
return (ERROPEN); 

if (FileLength > 50000) /* Test file length. */ 

return (ERRTOOBIG)? 

/* Make heap 20% larger than size of file. */ 

HeapSize = (USHORT)(FileLength + FileLength / 5); 

HHeap = WinCreateHeap /* Allocate a heap. */ 

(0, /* Segment address: 0 means allocate new segment. */ 

HeapSize, /* Initial heap size. */ 

0, /* Minimum increase size: 0 means use default. */ 

0, /* Minimum # of dedicated free lists: none. */ 

0, /* Maximum # of dedicated free lists: none. */ 

0)? /* Options: none. */ 

FarPtr = WinLockHeap (HHeap); /* Get far address of base of heap. */ 

HeapSelector = SELECTOROF (FarPtr)?/* Extract selector value. */ 

LastLine = -1; /* Initialize index of last line. */ 

while (fgets (LineBuffer,LINEBUFSIZ-1,PtrFile) != NULL) 

{ 

if (++LastLine >= MAXLINES) /* Test limit of number of lines. */ 

return (ERRMAXLINES)? 

LineLength = (unsigned char)strlen (LineBuffer) + 1;/* Include null*/ 

if (LineLength == LINEBUFSIZ - 1 && /* Insert '\n' into */ 

LineBuffer [LINEBUFSIZ - 3] != ' \n') /* overlength lines. */ 


{ 

LineBuffer [LINEBUFSIZ - 2] = '\n‘? 
LineBuffer [LINEBUFSIZ - 1] = '\0'? 
++LineLength; 

} 


HeapOffset = WinAllocMem /* Allocate block from heap. */ 

(HHeap, /* Heap handle. */ 

LineLength); /* Length of line to store. */ 

if (HeapOffset == NULL) /* Test for error. */ 

return (ERRALLOC); 

/* Copy line into heap block. */ 

movedata (LineSalector,LineOffset,HeapSelector, 

(unsigned)HeapOffset,LineLength); 


/* Insert line information into the table. 

LineTable [LastLine].LineAddress = MAKEP (HeapSelector,HeapOffset); 
LineTable [LastLine].LineLength = LineLength; 

} 
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*** Place line 0 in working buffer. *****************************************/ 
GetTempBuf (0) ; 

fclose (PtrFile) ; /* Close the file. */ 

return (0); 

} /* end of ReadFile */ 
void ReleaseTempBuf 

(int Line) /* Number of line held in 'LineBuffer'. */ 

/* 

This function: 

o Allocates a new block of memory just large enough to hold the string in 
the 'LineBuffer' 

o Copies the string into the new block 
o Adjusts the address in 'LineTable' 

V 

{ 

NPCH HeapOffset; /* Offset of block within heap. */ 

/*** Allocate a block to hold current contents of 'LineBuffer'. **************/ 
HeapOffset = WinAllocMem 
(HHeap, 

LineTable [Line].LineLength); 
if (HeapOffset == NULL) 

( 

sprintf (Message,"out of heap memory; line %d",_LINE_); 

ErrorQuit (Message); 

} 

/*** Copy characters from 'LineBuffer' into new block in heap. ***************/ 


movedata /* Intersegment block copy. */ 

(LineSelector, /* Source: selector of line buffer. */ 

LineOffset, /* Source: offset of line buffer. */ 

HeapSelector, /* Target: selector of heap. */ 

(unsigned)HeapOffset, /* Target: offset of new block. */ 

LineTable [Line].LineLength); /* Bytes to copy. */ 


/*** Adjust address in 'LineTable' to point to new block. ********************/ 
LineTable [Line].LineAddress = MAKEP (HeapSelector, HeapOffset); 

} /* end ReleaseTempBuf */ 


/*** Utility functions. ******************************************************/ 

void ErrorQuit /* Terminate program due to fatal error condition. */ 

(char ^Message) /* Error message to display to user. */ 

( 

char Buffer [60]; 

sprintf (Buffer,"Program Error: %s",Message); 

WinMessageBox /* Display a message box. */ 
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(HWND_DESKTOP, 

/* 

Handle of parent 

: desktop window. 

V 

HFrame, 

/* 

Handle of owner: 

frame window. 

V 

Buffer, 

/* 

Message text. 


V 

"PM Text Editor", 

/* 

Caption. 


V 

0, 

/* 

Help window ID:: 

not needed. 

V 

MB OK | 

/* 

Display an ’OK' 1 

button. 

*/ 

MB_ICONHAND); 

/* 

Display a hand icon. 

*/ 

Quit (1) ; 

/* 

Call normal termination function. 

V 


} /* end ErrorQuit */ 


void Quit 

(int ErrorCode) /* Process termination status. */ 

/* 

Calls Presentation Manager termination functions and ends program 
with specified error code. 

*/ 

( 

if (HHeap != NULL) 

WinDestroyHeap (HHeap); 

WlnDestroyWindow (HFrame); 

WinDestroyMsgQueue (HMesQue); 

WinTerminate (HAncBlk); 
exit (ErrorCode) ; 

} /* end Quit */ 
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his chapter incorporates a menu into the growing collec¬ 
tion of features for the Presentation Manager text editor. 
Menus are a high-level facility offered by the Presenta¬ 
tion Manager, and they are an important part of the uni¬ 
form user interface. The example program uses a menu to implement 
commands for managing files, for terminating the program, for locating 
strings or specific line numbers, and for selecting program options. 
Many of the menu commands can also be directly activated through 
keystrokes that are termed keyboard accelerators. 

Menus and keyboard accelerators are among the objects known as 
Presentation Manager resources. In this chapter, you will learn how to 
design menus and designate accelerator keys using a resource script; 
you will learn how to incorporate a menu into the standard window 
collection and how to install accelerator keys; and you will learn how to 
manage menus and accelerators by processing the messages these ob¬ 
jects send to the client window. The chapter will also show you how to 
implement the menu commands that do not require dialog boxes or 
other features presented in later chapters. Specifically, the chapter 
describes routines for saving the existing file, creating a new file, ter¬ 
minating the program, displaying an About box (a program informa¬ 
tion window), searching for a string, moving the cursor to a specific line 
number, and toggling between insert and overwrite editor modes. 

In this chapter, you will be introduced to two new buffer-management 
functions and five new supporting utility functions. The next complete 
program listing is Figure 8.38, which is given at the end of Chapter 8; this 
listing incorporates the features described in this chapter as well as the 
dialog boxes and dialog procedures presented in Chapter 8. 


CREATING MENUS 
• AND ACCELERATORS 

Menus and accelerator keys are examples of Presentation Man¬ 
ager resources. Resources are a special form of read-only data that are 
stored directly in the executable program file on disk (the .EXE file), and 
are read into memory when required at run-time. Resource data differ 
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from normal initialized program data. Normal initialized data (such as 
strings and initialized external or static variables) are defined in the .C 
source file and are placed by the linker into one or more data segments 
in the .EXE file. Resource data, however, are not defined within the .C 
source file; rather, they are inserted directly into the .EXE file after it has 
been created by the linker. Resources are placed into special resource 
segments (each resource, such as a menu or keyboard accelerator table, 
is given a separate segment); these segments are not read until they are 
actually required by the program at run-time. Also, since resource seg¬ 
ments are marked as read-only, they can be shared by several instances 
of the same program, and they may be discarded (and subsequently 
reloaded) if additional memory space is required. (Note that resource 
data can also be placed in dynamic-link library files, discussed in Chap¬ 
ter 1, so that they can be shared by several different programs.) 

Resources are prepared and inserted into the .EXE file by a utility 
known as the resource compiler. The general process for creating Presen¬ 
tation Manager resources is illustrated in Figure 7.1. The first step is to 
define the resources within a script file (with the extension .RC), which 
is a normal ASCII file analogous to a .C source file. Using the resource 
compiler, this file is then converted into a binary resource file (with the 
.RES extension). The final step is to use the resource compiler once 
again to insert the binary data from the .RES file directly into the .EXE 
file. The manner in which a resource is loaded and used at run-time 
depends upon the specific resource. This chapter describes the menu 
and accelerator-key resources used by the example program; Chapter 8 
describes the dialog boxes used by this program; and Chapter 10 
describes icons, bitmaps, and other Presentation Manager resources. 

Figure 7.2 lists the resource script used to define the menu and ac¬ 
celerator keys for the example program. Note that the script first includes 
the header file OS2.H so that it can use the system constant identifiers. It 
also includes the header file FIG7_3.H, listed in Figure 7.3, which defines a 
set of additional constants used to create and manage the menu and ac¬ 
celerator table; this file must also be included in the .C source file so that it 
can reference these same identifiers when managing the resources. 

The menu definition, which follows the keyword MENU and the 
identifier IDJFRAMERESOURCE, is enclosed between the words 
BEGIN and END. The constant IDFRAMERESOURCE (defined in the 
header file of Figure 7.3) will be used to identify the menu resource 
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#include <0S2.H> 
#include "FIG7 3.H 


MENU ID FRAME RESOURCE 


SUBMENU 

"'File", 

ID_FILE 

BEGIN 



MENUITEM 

""New", 

ID NEW 

MENUITEM 

"'Open...\tF3", 

ID OPEN 

MENUITEM 

"~Save\t~S F2", 

ID SAVE 

MENUITEM 

"Save 'As...", 

ID SAVEAS 

MENUITEM 

"'Print\t~P F4", 

ID_PRINT 

MENUITEM 

SEPARATOR 


MENUITEM 

""Exit", 

ID EXIT 

MENUITEM 

"A'bout.. 

ID_ABOUT 

END 



SUBMENU 

"'Edit", 

ID_EDIT 

BEGIN 



MENUITEM 

"Cu~t\tShift+Del", 

ID CUT 

MENUITEM 

"~Copy\tCtrl+Ins", 

ID COPY 

MENUITEM 

"~Paste\tShift+Ins", 

ID_PASTE 

END 



SUBMENU 

"'Search", 

ID_SEARCH 

BEGIN 



MENUITEM 

"~ Find...\t~ F", 

ID FIND 

MENUITEM 

"Find ~Next\t~N", 

ID FINDNEXT 

MENUITEM 

"~Go to Line...\t~G", 

ID_GOTOLINE 

END 



SUBMENU 

"'Options", 

ID_OPTIONS 

BEGIN 



MENUITEM 

"Overwrite Mode\tIns", 

ID_INSERT 

END 



MENUITEM 

"Fl=Help", 

ID HELP, 
MIS_HELP | ] 

END 



ACCELTABLE ID FRAME 

_RESOURCE 


BEGIN 




VKJDELETE, 
VK_INSERT, 
VK_F2, 
VK_F3, 
VK_F4, 
VK_INSERT, 
VK_INSERT, 
" * F", 

"“N", 

"*G" , 

"~P", 

,r S", 

END 


ID_CUT, 
ID_COPY, 
ID_SAVE, 
ID_OPEN, 
ID_PRINT, 
ID_INSERT, 
ID_PASTE, 
ID_FIND 
ID_FINDNEXT 
ID_GOTOLINE 
ID_PRINT 
ID SAVE 


VIRTUALKEY, 

VIRTUALKEY, 

VIRTUALKEY 

VIRTUALKEY 

VIRTUALKEY 

VIRTUALKEY 

VIRTUALKEY, 


SHIFT 

CONTROL 


• Figure 7.2: 

The resource script used to create a menu and define accelerator keys for the example program 
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#define 

ID_FRAME_RESOURCE 

1 

#define 

ID FILE 

10 

#define 

ID NEW 

11 

#define 

ID OPEN 

12 

#define 

ID SAVE 

13 

#define 

ID SAVEAS 

14 

#define 

ID PRINT 

15 

#define 

ID EXIT 

16 

#define 

ID_ABOUT 

17 

#define 

ID EDIT 

20 

#define 

ID CUT 

21 

#define 

ID COPY 

22 

#define 

ID_PASTE 

23 

#define 

ID SEARCH 

30 

#define 

ID FIND 

31 

#define 

ID FINDNEXT 

32 

#define 

ID_GOTOLINE 

33 

#define 

ID OPTIONS 

40 

#define 

ID_INSERT 

41 

#define 

ID_HELP 

50 


® Figure 7 . 3 : 

Constant definitions used for the menu and accelerator-key resources 

when creating the standard window collection through the call to Win- 
CreateStdWindow. The menu definition contains two types of top- 
level entries: those identified with the keyword MENUITEM and those 
identified with SUBMENU. For each of these top-level items, the key¬ 
word is followed by a string, which will appear permanently on the 
horizontal menu bar at the top of the window, and an identifier, which 
will be used by the program to manage the item. When the user selects 
an item labeled with MENUITEM, the program immediately executes 
the associated command; when, however, the user selects a SUBMENU 
item, the system temporarily displays a pull-down submenu. An item is 
selected either by clicking on it with the mouse, or by pressing the Enter 
key while the item is highlighted. 

The menu definition in Figure 7.2 contains the top-level items listed 
in Table 7.1. The horizontal menu containing these top-level entries is 
illustrated in Figure 7.4. Note that the submenus associated with each 
top-level SUBMENU item are defined as nested lists of MENUITEM 
entries; these entries are displayed in a temporary vertical pull-down 
menu when the user selects the associated top-level item. When the 
user subsequently selects a submenu item, the related command is im- 
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• Figure 7.4: 

The top-level menu displayed by the example program 


keyword SEPARATOR generates a horizontal bar that separates menu 
items. An example of a pull-down menu is shown in Figure 7.5. 

Note that many of the menu strings contain a tilde (~). When the sys¬ 
tem displays the menu, it underlines the character immediately follow¬ 
ing the tilde (the tilde is not actually displayed), and allows the user to 
select the associated item by simply typing this character. Many of these 
strings also display the name of a keystroke following the menu item 


• Table 7.1: Top-level Menu Items Defined for the Example Program 


Keyword 

String 

Identifiers 

Styles 

SUBMENU 

"-File", 

ID_FTLE 


SUBMENU 

"-Edit", 

ID_EDIT 


SUBMENU 

"-Search", 

IDSEARCH 


SUBMENU 

"-Options", 

IDOPTIONS 


MENUITEM 

"Fl=Help", 

IDJHELP, 

MIS_HELP 1 

MIS_BUTTON- 

SEPARATOR 
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label (for example, F2); these keystrokes are keyboard accelerators, 
which cause immediate activation of the corresponding command 
without requiring the user to go through the menu. (The symbol \t 
generates a tab that vertically aligns the accelerator key names.) 

The application program and the system use the constants, such as 
ID_FILE and ID_NEW, to identify the specific submenus and menu 
items. The manner in which the example program employs these iden¬ 
tifiers is explained in the next section. You can select arbitrary values for 
such identifiers; however, the identifier for each menu item should be 
unique. (The constants used in the resource script of Figure 7.2 are 
defined in Figure 7.3.) 

Note that the definition of the last menu item (ID_HELP) contains an 
additional field following the identifier. This optional field is used to 
specify one or more menu styles or flags, which are combined with the 
bitwise OR operator. The predefined identifier MIS_HELP (defined in 
PMWIN.H) causes the item to generate a WM_HELP message rather 
than a WM_COMMAND message (explained in the next section). The 
identifier MISJBUTTONSEPARATOR causes the system to separate the 
item with a vertical bar and prevents the user from moving the high¬ 
light to that item. The user can execute the help command from the key¬ 
board by pressing the FI key. (Pressing FI automatically generates a 
WMJHELP message; this key thus acts like a built-in accelerator.) 



® Figure 7.5: 

The pull-down menu displayed when the user selects the File submenu 











® 308 Programmer's Guide to the OS/2 Presentation Manager 


The second part of Figure 7.2 defines the list of accelerator keys. This 
resource is labeled with the keyword ACCELTABLE, followed by the 
identifier IDFRAMERESOURCE; note that the identifier must be 
the same as that used for the menu, since, as you will see, only a single 
constant is passed to the WinCreateStdWindow function to identify 
both resources. 

The definition of each accelerator key consists of three main fields. The 
first field identifies the keystroke by supplying either a virtual-key code or 
a string containing t^e appropriate character. The virtual-key codes, such 
as VK_DELETE for the Del key, are listed in Table 6.1. The caret symbol ( A ) 
preceding a character in a quoted keystroke indicates that the Ctrl key 
must be pressed in conjunction with the character key; for example, //A F" 
represents the Ctrl-F keystroke. 

The second field gives the identifier of the menu item that is to be ac¬ 
tivated by the accelerator key. In other words, pressing the accelerator 
key will generate a message containing this identifier exactly as if the 
corresponding menu item had been selected; this process is explained 
in the next section. 

The third field specifies one or more options, separated by commas 
C not combined with the bitwise OR operator). The VIRTUALKEY value 
indicates that the first parameter contains a virtual-key code (otherwise, 
the resource compiler will assume that the first parameter supplies a 
quoted character). The SFIIFT option specifies that the Shift key must be 
down when the accelerator key is pressed, and the CONTROL option 
similarly specifies that the Ctrl key must be pressed in conjunction with 
the accelerator key. (You can likewise use the ALT option for the Alt key; 
see the technical documentation for explanations of the other options.) 
For example, the line 

VK_INSERT, ID_COPY, VIRTUALKEY, CONTROL 

defines the Ctrl-Ins keystroke as a keyboard accelerator that generates a 
message containing the ID_COPY value; this is the same message sent 
when the user selects the ID_COPY item of the ID_EDIT submenu. 

Once you have prepared a resource script, which is contained in a file 
with the .RC extension, the next step is to use the resource compiler to 
convert this file into a binary format (contained in a .RES file) and then 
insert the binary resource data directly into the .EXE file. The MAKE file 
provided at the end of Chapter 8 (Figure 8.33) performs these steps 
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using the following two commands: 

rc /r FIG8_36.RC 

rc FIG8_36.RES FIG8_38.EXE 

The first command, which is executed only if the resource script has 
been modified, converts the script file (FIG8_36.RC) into a binary 
resource file (FIG8_36.RES). The second command is performed each 
time a new .EXE file is prepared; this command inserts the binary data 
from FIG8_36.RES directly into the executable file, FIG8_38.EXE. You 
can perform both of these steps using the following single command: 

rc FIG8_36.RC FIG8_38.EXE 

The MAKE file of Figure 8.33, however, performs these steps separately 
to avoid unnecessarily recompiling the resource script each time the 
.EXE file is prepared. As you can see from the MAKE file, the script is 
compiled only if the .RC file (or the header file it includes) has been 
modified. 

When the executable file is loaded, the resource segments are not 
automatically read into memory. Rather, the system reads a specific 
resource segment only when the information is required. In the ex¬ 
ample program, the resource data for the menu and accelerator table 
are read when the standard window is created through the call to Win- 
CreateStdWindow. The latest version of the call to this function is listed 
in Figure 7.6. Note that the second parameter (which specifies the frame 
window styles) now includes the value FS_ACCELTABLE, which 
causes the function to install an accelerator table. Also, the value as¬ 
signed to the variable CtlData (the address of which is passed as the 
third parameter) now includes the identifier FCFJMENU, which adds a 
menu to the set of control windows included in the standard window. 
The seventh parameter is set to 0, which indicates that the resources are 
contained within the program .EXE file (if the resource segments are lo¬ 
cated within a dynamic-link module, this parameter must contain the 
module handle returned by the DosLoadModule OS/2 function). 
Finally, the eighth parameter contains the resource ID for both the 
menu and the accelerator (this is the ID assigned to these resources in 
the script file, which must be the same for both resources). 
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ULONG CtlData = 

FCF_HORZSCROLL 

FCF_MENU 

FCF_MINMAX 

FCF_SHELLPOSITION 

FCF_SIZEBORDER 

FCF_SYSMENU 

FCF_TASKLIST 

FCF_TITLEBAR 

FCF_VERTSCROLL; 


/* Control windows to include. */ 
/* Horizontal scroll bar. */ 
/* Menu. */ 
/* Minimize/maximize box. */ 
/* Make window visible on screen. */ 
/* Wide sizing border. */ 
/* System menu. */ 
/* Display program name in Task Manager. */ 
/* Title bar. */ 
/* Vertical scroll bar. */ 


HFrame = WinCreateStdWindow /* Create parent window. */ 

(HWND_DESKTOP, /* Parent window handle. */ 

FS_ACCELTABLE | /* Install accelerator table. */ 

WS_VISIBLE, /* Frame window style. */ 

&CtlData, /* Address of control data. */ 

"MAIN", /* client window class name. */ 

/* Text for title bar. */ 

0L / /* Client window style. */ 

/* Resource module handle. */ 

ID_FRAME_RESOURCE, /* Resource identification. */ 


SHClient); /* Address to receive client window hand. */ 


• Figure 7.6: 

The call to the function WinCreateStdWindow 


Immediately after the call to WinCreateStdWindow, the function 
main obtains the handle of the newly created menu window by calling 
the function WinWindowFromID, as follows: 


HMenu = WinWindowFromID /* Get handle of */ 

/* menu window. */ 
(HFrame, /* Handle of parent frame window. */ 
FID_MENU); /* ID of menu child window. */ 


The window menu handle stored in the global variable HMenu is used 
later in the program. The function WinWindowFromID is described in 
Figure 4.5. 

The resource data supply all the information the system needs to con¬ 
struct the menu and accelerator table according to the specifications 
supplied in the original resource script. The next section discusses the 
messages sent when the user either selects a menu item or presses an 
accelerator key. 
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MANAGING MENUS 
. AND ACCELERATORS 

Once you have installed a menu and accelerator table through the 
call to WinCreateStdWindow, the system displays the menu and al¬ 
lows the user to access submenus and select menu items. The system 
window procedure manages the menu, automatically performing such 
tasks as displaying and removing pull-down submenus, and moving 
the highlight from one menu item to another in response to the arrow 
keys. The system sends messages to the client window whenever 
relevant events occur. Your program, therefore, need only respond to 
these messages and perform the requested commands. 

The example program processes the following three general mes¬ 
sages sent by the menu window procedure: 


Message ID 


Cause of Message 


WMJNITMENU 

WM_COMMAND 

WM_HELP 


A submenu is first displayed. 

The user has selected a menu item or 
pressed an accelerator key. 

The user clicked on the ID_HELP 
menu item or pressed the FI key. 


Accordingly, the main window procedure (WndProc) of the current 
version of the example program contains three additional branches in 
the switch statement to handle these messages. Note that no special 
processing is required to manage accelerator keys; the system automat¬ 
ically translates these keystrokes into the appropriate messages. 


The WMJNITMENU Message 

The system sends the WMJNITMENU message (Figure 7.7) 
whenever a menu item is about to become active. The example program 
processes this message in the function InitMenu, listed in Figure 7.8. 
This message gives the program an opportunity to perform any re¬ 
quired initialization tasks immediately before a submenu is displayed. 
The message supplies the identifier of the specific menu item in the 



312 Programmer's Guide to the OS/2 Presentation Manager 


low-order word of mpl. InitMenu contains initialization routines for 
the following three submenus: 


Menu Identifier 
(Low-order Word of mpl) 

Cause of Message 

ID_EDIT 

Edit pull-down submenu 
is being displayed. 

ID_SEARCH 

Search pull-down sub¬ 
menu is being displayed. 

ID_OPTIONS 

Options pull-down sub¬ 
menu is being displayed. 

WMJNITMENU 


Purpose: 


This message is sent by the system to the client window 
when a menu item is about to become active. 

Parameters: 


MPARAM mpl 


low-order word: 

Identifier of the menu item becoming 
active. 

high-order word: 

0. 

MPARAM mp2 

Menu window handle. 

Return Value: 


NULL. 


Notes: 


This message gives the client window procedure an oppor¬ 
tunity to perform any necessary initializations before a sub- 

menu is displayed. 



® Figure 7.7: 

The WM_INITMENU Presentation Manager message 
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MRESULT EXPENTRY InitMenu (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM m P 2) 

{ 

/*** Branch on the code for the specific submenu that is being displayed. ****/ 


switch (SHORT1FR0MMP (mpl)) 

{ 

case ID_EDIT; 


/* 'Edit' submenu. 


*/ 


WinSendMsg /* 

(HMenu, /* 

MM_S ETITEMATTR, /* 

MPFROM2SHORT 

(ID_CUT, /* 

TRUE), /* 

MPFR0M2SHORT 


(MIA DISABLED, /* 
/* 

BlockMarked ? 0 : 


Set attribute of 'Cut' menu item. 
Handle of menu window. _ 

Set attribute of menu item. 

'Cut' menu item. 

Include submenus. 

Disabled attribute. 

Disable only if block not marked. 
MIA_DISABLED) ) ; 


V 

*/ 

V 

*/ 

*/ 

*/ 

V 


WinSendMsg /* 

(HMenu, /* 

MM_SETITEMATTR, /* 

MPFR0M2SHORT 

(ID_COPY, /* 

TRUE), /* 

MPFR0M2SHORT 


(MIA_DISABLED, /* 

/* 

BlockMarked ? 0 ; 


Set attribute of 'Copy' menu item.*/ 


Handle of menu window. */ 

Set attribute of menu item. */ 

'Copy' menu item. */ 

Include submenus. V 

Disabled attribute. */ 


Disable only if block not marked. */ 
MIA_DISABLED)); 


WinSendMsg 

(HMenu, 

MM_SETITEMATTR, 
MPFR0M2SHORT 

(ID_PASTE, 
TRUE), 

MPFR0M2SHORT 

(MIA_DISABLED, 

ClipData ? 0 ; 


/* Set attribute of 'Paste* menu item*/ 


/* Handle of menu window. */ 

/* Set attribute of menu item. */ 

/* 'Paste' menu item. */ 

/* Include submenus. */ 

/* Disabled attribute. */ 


/* Disable if no data in clipboard. */ 
MIA_DISABLED))? 


return FALSE; 


case ID SEARCH; 


/* 'Search' submenu. 


*/ 


WinSendMsg 

(HMenu, 

MM_SETITEMATTR, 
MPFR0M2SHORT 

(ID_FINDNEXT, 
TRUE), 

MPFR0M2SHORT 

(MIA_DISABLED, 


/* Set attribute of 'Find Next' item.*/ 


/* Handle of menu window. */ 

/* Set attribute of menu item. */ 

/* 'Find Next' menu item. */ 

/* Include submenus. */ 

/* Disabled attribute. _ _ */ 


/* Disable if no search string given.*/ 


® Figure 7.8: 

The function InitMenu of the example program 
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Findstring [0] ? 0 : MIA_DISABLED)); 
return FALSE; 

case ID_OPTIONS: /* Options submenu. */ 

/* Se ^ raen u item text according to current insert status. */ 

WinSendMsg 

(HMenu, /* Menu handle. */ 

MMSETITEMTEXT, /* Set item text. */ 

MPFR0M2SHORT (ID_INSERT,0), /* ID of item. */ 

Insert ? (MPARAM)(PCH)"Overwrite Mode\tIns" /* Text. */ 
: (MPARAM)(PCH)"Insert Mode\tIns"); 

return FALSE; 

default: 

return FALSE; 

} /* end switch */ 

} /* end InitMenu */ 


• Figure 7.8: 

The function InitMenu of the example program (continued) 


Edit Submenu Initialization 

As you can see from the resource script of Figure 7.2, the Edit sub¬ 
menu contains three items: Cut, Copy, and Paste. These commands 
manage the exchange of data between the program and the Presenta¬ 
tion Manager clipboard, and are described in Chapter 9. The salient 
point for the current discussion is that at a given time it may not be pos¬ 
sible to execute one or more of these commands. Specifically, the pro¬ 
gram cannot perform the Cut or Copy operation unless a block of data 
is currently marked (the global program flag BlockMarked indicates 
whether a block is marked). Also, it cannot execute the Paste operation 
unless the Presentation Manager clipboard currently contains ap¬ 
propriate data (indicated by the flag ClipData). 

Accordingly, the initialization code disables all menu items for com¬ 
mands that cannot currently be executed, and enables menu items for 
those commands that can be executed. If an item is disabled, it is dis¬ 
played in a halftone font and cannot be selected (if the user attempts to 
select a disabled item, the menu will be removed as usual, but the sys¬ 
tem will not send the command message to the client window). 
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Menu items are enabled or disabled by sending the MM^SET- 
ITEMATTR message (Figure 7.9) directly to the menu window. The 
low-order word of the mpl parameter supplies the identifier of the 
menu item (ID_CUT, TD_COPY, or ID_PASTE). The high-order word 
contains a flag indicating whether submenus should be searched for the 
specified item; this flag must be set to TRUE, since all three of these 
menu items belong to submenus. The low-order word of the mp2 
parameter is assigned the value MIA_DISABLED, which specifies that 
the enabled status of the menu item is to be set. The high-order word is 
assigned the value MIA_DISABLED if the menu item is to be disabled, 
or the value 0 if the item is to be enabled. As you can see in the source 
code, each menu item is either disabled or enabled depending upon the 
current value of the appropriate variable: BlockMarked or ClipData. 


Search Submenu Initialization 

The Search submenu contains a Find item that allows the user to 
enter a string (which is stored in the global buffer FindString), and then 
searches for the first occurrence of this string in the file beyond the cur¬ 
sor position. The submenu also contains a Find Next item to locate the 
next occurrence of the same string; if, however, FindString does not 
currently contain a string, this menu item should be disabled. Accord¬ 
ingly, the Search submenu initialization routine sends a MM_SET- 
ITEMATTR message—in the same manner as the Edit menu 
routine—to either enable or disable this item, depending upon whether 
the FindString buffer is currently null. 

Options Submenu Initialization 

Finally, the InitMenu function contains a routine to initialize the 
Options submenu. This submenu contains a single item (ID_INSERT), 
which toggles the editor between insert and overwrite modes. When 
the editor is in the insert mode, the submenu item should display the 
string "Overwrite ModeXtlns", indicating that selecting the item will 
change the program to the overwrite mode. Likewise, when the pro¬ 
gram is in overwrite mode, the item should be labeled "Insert 
ModeXtlns". 
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MM_SETITEMATTR 


Purpose: 

This message is sent to a menu window to set the attributes 
of a menu item. 


Parameters: 

MPARAM mpl 

low-order word: 
high-order word: 


MPARAM mp2 

low-order word: 


Identifier of the menu item (as 
assigned in the resource script). 

A flag indicating, whether to search 
submenus for an item with the 
identifier given in the low-order word. 


A mask for the attribute (s) you would 
like to set; you can specify one or more 
of the following values (combined 
with the logical OR operator): 


Identifier Attribute 


MIA_CHECKED 

MIAJDISABLED 


MIAJFRAMED 


A check mark is 
displayed next to the 
menu item 

The menu item is 
disabled (if this 
attribute is not selected, 
the item is enabled) 

A frame is drawn 
around the menu item 


high-order word: A mask for the new values to be 

assigned to the bits specified by the 
low-order word. You can specify one 
or more of the same identifiers listed 
for the low-order word. 


• Figure 7.9: 

The MM_SETITEMATTR Presentation Manager message 
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Return Value: 

The menu window procedure returns TRUE if the service 
has been successfully performed, and FALSE if an error 
occurred. 

Notes: 

The original attributes of a menu item are specified in the 
resource script; this message, however, can be used to 
modify one or more attributes. 

If the high-order word of mpl is set to TRUE and the menu 
does not have an item with the specified identifier, the proce¬ 
dure searches submenus for the matching item. 

Note that each attribute is represented by a single bit in a 
bit mask; the attribute is enabled if the corresponding bit is 
on. The high-order word of mp2 is a bit mask specifying 
which attributes you want to modify; the low-order word is 
a bit mask indicating the actual desired value of each of these 
attributes. For example, if you wanted to enable the check 
mark but disable the frame, you would assign the high-order 
word of mp2 the value 

MIA_CHECKED | MIA_FRAMED 

and the low-order word the value 

MIA__CHECKED 

You can obtain the current state of an attribute for a given 
item by sending the message MM_QUERYITEMATTR. 


• Figure 7.9: 

The MM_SETITEMATTR Presentation Manager message (continued) 

Therefore, the initialization routine sets the text of this submenu item 
according to the current value of the Insert flag. The text is set by send¬ 
ing the MM_SETITEMTEXT message directly to the menu window. 
This message is described in Figure 7.10. 




MM_SETITEMTEXT 


Purpose: 

This message is sent to a menu control window to specify the 
text displayed for a given menu item. 

Parameters: 

MPARAM mpl 

low-order word: Identifier of the item (as assigned in 

the resource script), 
high-order word: 0. 

mparam mp2 Far pointer to a null-terminated string j 

containing the item text. 

Return Value: 

The menu window procedure returns TRUE if the service 
has been successfully performed, and FALSE if an error 
occurred. 

Notes: 

The original text for the menu item is specified in the 
resource script; this message, however, can be us< 
change the item text. 

• Figure 7.10: 

The MM_SETITEMTEXT Presentation Manager message 

The WM_COMMAND Message 

The system notifies the client window that the user has selected a menu 
command by sending a WM_COMMAND message (Figure 7.11). The only 
menu item in the example program that does not generate this message is the 
Help entry (ID_HELP), which is discussed in the next section. 

WM_COMMAND is a general-purpose message sent by control win¬ 
dows to their owners to signal significant events (in the case of a menu, 
the owner is the frame window, which passes the message on to the 
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WM_COMMAND 

Purpose: 

This message is sent by a control window to its owner to 
report a significant event. 

Parameters: 

MPARAM mpl 

low-order word: The command value, 

high-order word: 0. 

MPARAM mp2 

low-order word: Source of the message, which may be 

one of the following values: 

Identifier Message Source 

CMDSRC_PUSH- Push-button control 

BUTTON 

CMDSRC_MENU Menu control 

CMDSRC_ACCEL- Accelerator key 

ERATOR 

CMDSRC_OTHER Other source 

high-order word: If TRUE, the message was posted as 

the result of a pointer device 
operation; if FALSE, the message 
resulted from a keyboard operation. 

Return Value: 

NULL. 

Notes: 

See also a similar message, WM_CONTROL (Figure 8.18). 

® Figure 7.11: 

The WM_COMMAND Presentation Manager message 
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client window). This message is accompanied by a value (in the low- 
order word of mpl) that indicates the specific command. A menu con¬ 
trol window sends this message whenever the user selects a menu item, 
and passes the identifier of the selected item (which was specified in the 
resource file) as the command value. The system also sends this mes¬ 
sage—accompanied by the associated command value—when the user 
presses an accelerator key. 

The example program processes WM_COMMAND messages in the 
function Command (portions of the function are listed in this section; 
for a complete listing, see the source file in Figure 8.38, at the end of 
Chapter 8). This function consists of a large switch statement, which 
branches to the appropriate routine to process the selected menu item. 
The menu item identifier (passed as the message command code) is 
conveniently extracted using the COMMANDMSG macro, as follows: 

switch (COMMANDMSG (&msg)->cmd) 

This use of this macro is exactly analogous to the use of the CHARMSG 
macro, explained in Chapter 6 (in the section on The WM_CHAR Message). 

The menu selections listed in Table 7.2 are processed within the Com- 
mand function. 

Note that the descriptions of routines within this chapter are in the 
section on The Menu Commands. As mentioned previously, not all 
routines are described in the current chapter, since some of them require 
dialog boxes or other features presented later in the book. The routines 
described in Chapter 7 or 8 are implemented in the complete program 
listing given in Figure 8.38; for routines that require techniques 
presented in later chapters, this version of the program calls the func¬ 
tion NotYet. The NotYet function simply displays a message box in¬ 
dicating that a given routine has not yet been implemented (the name of 
the nonimplemented routine is passed as a parameter). The function 
NotYet is listed in Figure 7.12. 


The WM_HELP Message 

The last menu item defined in the resource script of Figure 7.2 is 
labeled "F1=HELP" and has the identifier ID_HELP. Because this item 
was defined with the MISJHGELP style, selecting it causes the system to 


send a WM_HELP message rather than a WM_COMMAND message. 
Pressing the FI key also generates a WMJHELP message. Note that you 
need not install FI as an accelerator key; it is automatically processed as 
an accelerator key by the system. 

The routine in the example program that handles the WMJHELP 
message simply calls the NotYet function to notify the user that the help 
facility has not yet been implemented. Implementing a help utility is 
not covered in this book, but rather is left as a project for the reader. 


® Table 7.2: Menu Selections Processed within the Command Function 


ID 

Menu Item 

Description 

ID_NEW 

New (File submenu) 

Chapter 7 

IDOPEN 

Open (File submenu) 

Chapter 8 

ID_SAVE 

Save (File submenu) 

Chapter 7 

ID_SAVEAS 

Save As (File submenu) 

Chapter 8 

ID_PRINT 

Print (File submenu) 

Chapter 12 

IDEXIT 

Exit (File submenu) 

Chapter 7 

IDABOUT 

About (File submenu) 

Chapter 8 

IDCUT 

Cut (Edit submenu) 

Chapter 9 

ID_COPY 

Copy (Edit submenu) 

Chapter 9 

ID_PASTE 

Paste (Edit submenu) 

Chapter 9 

IDJFIND 

Find (Search submenu) 

Chapter 8 

ID_FINDNEXT 

Find Next (Search sub¬ 
menu) 

Chapter 8 

ID_GOTOLINE 

Go to Line (Search sub¬ 
menu) 

Chapter 8 

ID_INSERT 

Overwrite Mode/Insert 
Mode 

(Options submenu) 

Chapter 7 
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void NotYet (char ^Message) 



1 

char Buffer [60]; 



/* Format message, 
sprintf (Buffer,"Not Yet 

Implemented: %s",Message) ? 

*/ 

WinMessageBox 

/* Display a message box. 

*/ 

(HWND_DESKTOP, 

/* Handle of parent -- try frame. 

*/ 

HFrame, 

/* Handle of owner. 

V 

Buffer, 

/* Message text. 

*/ 

"PM Text Editor", 

/* Caption. 

V 

0, 

/* Help window ID: not needed. 

*/ 

MB OK | 

/* Display an ’OK' button. 

*/ 

MB_ICONASTERISK); 

/* Display an asterisk. 

*/ 

} /* end NotYet */ 




• Figure 7.12: 

The function NotYet of the example program 


• THE MENU COMMANDS 

This section describes the routines for executing the menu com¬ 
mands that do not require dialog boxes or other features treated in sub¬ 
sequent chapters. Each of these routines is contained in a branch of the 
switch statement, within the function Command. 


The New Command 

The routine for the New command of the File submenu is listed in 
Figure 7.13. This routine is executed whenever the WM_COMMAND 
message has a command value of ID_NEW, the identifier assigned to 
the New menu item within the resource script. The New command 
clears the current contents of the file buffer and reinitializes the buffer 
for a new, empty file that is initially unnamed. 

The routine first checks the Modified variable to determine whether 
the file buffer contains modified data that has not been saved to disk. 
This global variable is defined in the program as follows: 

unsigned char Modified = 0; 
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Modified is initialized to 0 whenever a file is first read or saved to disk, 
and it is set to 1 whenever the user modifies the file data contained 
in the buffer. (Note that the Character function and the Del-key and 
F9-key routines of the VirtKey function now set this flag to 1 before 
altering the file buffer; you will see how it is processed by the file- 
management routines.) 

If the buffer has been modified, the routine warns the user by dis¬ 
playing a message box through a call to WinMessageBox (Figure 3.14). 
The message box displays a string asking the user whether the current 
file should be saved, and it contains a Yes button and a No button; Win¬ 
MessageBox returns a code indicating which of these buttons the user 


case ID_NEW: /* 'New' file menu item. */ 

if (Modified) /* File is modified. 

{ 

/* Warn user and elicit response on saving file. 

Reply = WinMessageBox 
(HWND_DESKTOP, 
hwnd, 

"File Unsaved; Save?", 
iiPM Text Editor", 

0, 

MB_YESNO | 

MB_ICONQUESTION); 

/* If reply is Yes, send a 'Save* message to client. */ 

if (Reply == MBID_YES) 

/* Repeat message until file successfully saved. */ 
while (Modified) 

WinSendMsg 

(hwnd, 

WM_COMMAND, 

MPFROM2SHORT (ID_SAVE, 0), 

0L) ; 

} /* end if Modified */ 


ReleaseFile (); /* Free current heap. */ 
NewFile ()? /* Initialize a new file. */ 
FileName [0] = '\0 1 ; /* New file is untitled. */ 
ShowFileName (); /* Display "Untitled" in title bar. */ 
Modified =0; /* Reset modified flag. */ 
InitWindow (); /* Set initial window/cursor values. */ 


return FALSE; 


® Figure 7.13: 

The routine for the New command of the File submenu 


*/ 

V 
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selected. If the user chooses to save the file, the program then sends a 
WM_COMMAND message (with an ID_SAVE command code) back to 
the client window. This recursive message activates the Save routine, 
described later in the chapter, exactly as if the user had selected this 
item from the File submenu. 

The routine now performs a series of steps to reinitialize the file buff¬ 
er and the data displayed within the window for a new, empty, and un¬ 
named file. First, it calls the function ReleaseFile (Figure 7.14), which is 
in the buffer-management module and serves to release the current file 
data by destroying the Presentation Manager heap that had been allo¬ 
cated when the file was first created or read from the disk. It then calls 
the function NewFiie, described in Chapter 6, to initialize a new, empty 
file within the file buffer. 

The routine next assigns the value NULF to the first character of the 
string FileName. FileName is a global string that contains the fully 
qualified name of the current file (that is, the file name including the 
drive and full directory path specifications). Whenever the file is cur¬ 
rently unnamed, the first character of this string is set to NUFF. 

In the present version of the example program, the function main as¬ 
signs an initial value to FileName. If the user has not entered a file name 
on the command line, it sets the first character of FileName to NUFF to 
indicate an unnamed file. If, however, the user included a file name on 
the command line, main assigns the fully qualified version of this name 
to FileName. The fully qualified path name corresponding to a given 


void 

ReleaseFile (void) 


/* 

Destroys the current 

heap, thereby freeing all file data. 

V 

{ 

if (HHeap != NULL) 



WinDestroyHeap 

(HHeap); 


return; 



} /* end ReleaseFile 

*/ 


• Figure 7.14: 

The ReleaseFile fund ion of the example program 
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file is obtained through the function Qualify, which is called from func¬ 
tion main as follows: 


Qualify (argv [1], FileName); 

Qualify is a utility function contained within the example program and 
is listed in Figure 7.15. 

Qualify accepts a file name (given by the first parameter) and con¬ 
verts this name—if necessary—to a fully qualified name, which is writ¬ 
ten to the string specified by the second parameter. If the input name 


void Qualify (char *Unqual, char *Qual) 

/* 

Converts file name •Unqual* (either a simple or qualified file name) to 
a fully qualified file name, which includes the drive specification and 
full directory path, and is copied to 'Qual'. 


char PathBuffer [PATHLENGTH]; 
char *PtrPath = PathBuffer; 

GetPath (PathBuffer, sizeof (PathBuffer)); 

if (*(Unqual + 1) == 1 :') 

{ 

*Qual++ = *Unqual++; 

*Qual++ = *Unqual++; 

PtrPath += 2; 

} 

else 

{ 

*Qual++ = *PtrPath++; 

*Qual++ = *PtrPath++; 

) 

if (*Unqual 1= '\\') 

{ 

while (*Qual++ = *PtrPath++) 

if (* (Qual - 2) == *\V) 

—Qual; 

else 

*(Qual - 1) = '\\'; 

) 

while (*Qual++ = *Unqual++) 


/* end Qualify */ 


Figure 7.15: 

The Qualify function of the example program 
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already contains a full drive and path specification, it is simply copied 
to the output name. If the input name lacks a drive specification, the 
function adds the current default drive to the output name; and if 
the input name lacks a full directory path (which must begin from the 
root directory), the function adds the current directory path to the out¬ 
put name. (Note that under OS/2, the system maintains a separate 
default drive and directory for each process.) 

Qualify obtains the current disk drive and directory path by calling 
another utility function, GetPath (listed in Figure 7.16). GetPath calls 
two OS/2 kernel functions; it obtains the current drive through Dos- 
QCurDisk and the current directory path through DosQCurDir. 

Note that the program must save the fully qualified file name be¬ 
cause, as you will see in Chapter 8, the user can change the current drive 
or directory at any time through the Open menu command. If the 


void GetPath (char *Path, int PathSize) 

/* 

Copies fully qualified path to 'Path’; will not copy beyond the length of 
'Path' given by PathSize. 

*/ 


USHORT DriveNumber; /* Disk drive number. _ */ 

ULONG LogicalDrives; /* Mapping of installed drives. */ 

/* If target buffer is too small, return without altering it. */ 

if (PathSize < 3) 
return; 

/* Obtain current default disk and mapping of installed drives. */ 

DosQCurDisk 

(&DriveNumber, /* Receives number of current drive. */ 

SLogicalDrives); /* Receives mapping of installed drives. */ 

/* Write drive letter to 'Path'. */ 

sprintf (Path,"%c:\\",DriveNumber + 64); 

/* Adjust 'PathSize' for drive specification. */ 

PathSize -= 3; 

/* Obtain current default directory. */ 

DosQCurDir 

(DriveNumber, /* Drive number: current drive. */ 

Path +3, /* Address of buffer to receive directory. */ 

&PathSize)? /* Length of buffer to receive directory. */ 


return; 

} /* end GetPath */ 


® Figure 7.16: 

The GetPath utility function of the example program 






Using Menus and Accelerators 327 




program did not store the drive and directory associated with the cur¬ 
rent file, this file could easily be written to the wrong directory when it 
is saved. 

Once FileName has been set to an empty string indicating an un¬ 
named file, the routine for the New command calls the ShowFileName 
utility function (listed in Figure 7.17) to update the file name displayed 
in the window title bar. The present version of the example program 
displays the name of the current file along with the name of the pro¬ 
gram within the title bar. The function main specifies an empty title ("") 
in the call to WinCreateStdWindow and then immediately calls Show- 
FileName to set the appropriate title. The function ShowFileName sets 
the title text by calling the Presentation Manager function WinSet- 
WindowText, which is described in Figure 7.18. Before setting the title 
bar, the function ShowFileName formats the title bar text using the fol¬ 
lowing command: 

sprintf (Title, "PM Editor - %s", FileName[0] 

? Unqualify (FileName) : "(Untitled)"); 

The file name written to the title bar text (Title) by this command is 
either the current file name, or the string "(Untitled)" if FileName is 
empty. Note, however, that rather than displaying the fully qualified 
file name, the program obtains the simple file name by calling the utility 
function Unqualify (listed in Figure 7.19). 


void ShowFileName (void) 

/* 

Updates the text in the title bar to show the current file name. 

V 

{ 

/* Format title. */ 

sprintf (Title, "PM Editor - %s", FileName[0] ? Unqualify (FileName) 

• "(Untitled)"); 

/* Modify the title bar window text. */ 

WirSetWindowText 

(HFrame, /* Window handle: frame routes text to menu. */ 

Title); /* String containing the text. */ 

} /* end ShowFileName */ 


• Figure 7.17: 

The ShowFileName function of the example program 
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Unqualify locates the simple file name (that is, the name and exten¬ 
sion without the drive or directory specifications) within the string con¬ 
taining a fully qualified name that is passed as a parameter. It then 
converts the simple name to uppercase letters, and returns a pointer to 
the portion of the string containing this name. The characters of the 
simple name are converted to uppercase using the Presentation 
Manager function WinUpper, which is described in Figure 7.20. Thus, 
all file names displayed in the title bar are simple names in uppercase 
letters, in conformance with the Presentation Manager style guidelines. 


WinSetWindowText 

Purpose: 

Sets the text associated with a window. 

Prototype: 

BOOL APIENTRY WinSetWindowText 

(hwnd hwnd, Handle of the window. 

PSZ pszText ) ; A null-terminated string containing the text 
to be assigned to the window given by hwnd. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

The manner in which the text passed to this function is used 
depends upon the specific target window. If hwnd is the frame 
window handle, the specified text is displayed in the title bar 
control window. 

Related Function: 

WinQueryWindowText (Figure 8.16) 


© Figure 7.18: 

The WinSetWindowText Presentation Manager function 
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Finally, after resetting the Modified flag to 0, the New file routine 
calls the utility function InitWindow to initialize the window for a 
new file. This function is listed in Figure 7.21, and performs the follow¬ 
ing tasks: 

® It sets the global variables CursorCol and CursorLine to 0 so that 
the cursor is associated with the first character of the new file. 

® It sets TopLine and FirstCol to 0 so that the beginning of the file 
is displayed in the window. 

® It adjusts TopLineMax and FirstColMax to reflect the current 
size of the file and dimensions of the window. 

® It adjusts the positions and ranges of the vertical and horizontal 
scroll bars. 

© It positions the cursor at the upper left corner of the window. 

© It invalidates the entire window to force the Paint function to dis¬ 

play the new file data. 


char *IJnqualify (char *Qual) 

/* 

Returns a pointer to the simple file name within the string 'Qual', 
which contains a partially or fully specified file path. Converts the 
unqualified file name to upper case. 

*/ 

( 

char *PtrCh; 

PtrCh = Qual + strlen (Qual); 

while (PtrCh 1= Qual && 

*(PtrCh-1) != 'W && 

*(PtrCh-1) != ':') 

—PtrCh; 

WinUpper 

(HAncBlk, 

NULL, 

NULL, 

PtrCh); 

return (PtrCh); 

} /* end Unqualify */ 


© Figure 7.19: 

The Unqualify function of the example program 


/* Convert unqualified name to upper case.*/ 


/* Anchor block handle. */ 
/* Code page: use current. */ 
/* Country code: use default. */ 
/* Address of string to be converted. */ 








• 330 Programmer's Guide to the OS/2 Presentation Manager 


WinUpper 

Purpose: 

Converts the characters in a string to uppercase. 

Prototype: 

SHORT APIENTRY 
(HAB hab, 

USHORT idcp, 

USHORT idee, 

PSZ psz); 

Return Value: 

The length of the converted string. 

Notes: 

The function directly modifies the characters in the string 
passed through the parameter psz (that is, the string is 
modified in place). 


WinUpper 

Anchor block handle. 

Code page to use; a NULL value causes the 
function to use the code page for the current 
process. 

Country code; a NULL value causes the 
function to use the default country specified 
in the CONFIG.SYS file. 

Pointer to the string to be converted. 


• Figure 7.20: 

The WinUpper Presentation Manager function 


The Save Command 

The routine for the Save command of the File submenu is listed in 
Figure 7.22. This routine is executed in response to a WM_COMMAND 
message with an ID_SAVE command code, which is generated when¬ 
ever the user selects the Save menu item or presses the Ctrl-S accelerator 
keystroke. If the current file has been named (that is, FiieName is not 
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void InitWindow (void) 

/* 

This function initializes the window when a new file is read ('Open' 
file menu item), or when a new empty file is started ('New® file menu 
item). It performs the following tasks: 

o Initializes global cursor and window variables so that the cursor 
is placed at the first character of the file, and the beginning of 
the file is displayed in the window, 
o Adjusts range and position of horizontal and vertical scroll bars., 
o Positions the cursor at top left of window. 

o Invalidates the entire window to force displaying the new data. 


CursorCol = CursorLine = 0; 

TopLine = FirstCol = 0; 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1)? 

FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 

WinSendMsg /* Adjust range/position of slider. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable scroll bar if scrolling is possible. */ 

(HVScroll, /* Recipient handle (vertical scroll bar).*/ 

TopLineMax ? TRUE : FALSE); /* Enable only if max. 1= 0. */ 

WinSendMsg /* Adjust range/position of slider. */ 

(HHScroll, /* Recipient handle: horizontal scroll bar*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (FirstCol, 0), /* Position. */ 

MPFROM2SHORT (0, FirstColMax)) ; /* Range. */ 

If (HClient == WinQueryFocus (HWND_DESKTOP,FALSE)) 

WinCreateCursor /* Set cursor position. */ 


(HClient, 

(CursorCol - FirstCol) * xChar, 
yWin - (CursorLine - TopLine +1) * yCharTot, 
0 , 

0 , 

CURSOR_SETPOS, 

NULL) ; 


WinlnvalidateRect 

/* 

Invalidate entire window. 

*/ 

(HClient, 

/* 

Client window handle. 

*/ 

0 , 

/* 

Rectangle: 0 means whole window. 

V 

FALSE); 

/* 

Do not automatically include children. 

*/ 


} /* end InitWindow */ 


• Figure 721: 

The function InitWindow of the example program 
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empty), the routine saves the file under this name and returns; if, how¬ 
ever, the file is unnamed, the Save routine drops through to the Save As 
routine (described in Chapter 8), which obtains a file name from the 
user before saving the file. 

The file is saved by calling the SaveFile function of the buffer- 
management module (listed in Figure 7.22), which is passed the fully 
qualified file name. SaveFile is similar to ReadFile (described in Chap¬ 
ter 3); it opens and closes the file using the high-level C functions fopen 
and fclose, and writes each file line using the fputs function. See the 
section on enhancements, at the end of the chapter, for several sugges¬ 
tions on improving this routine. 


int SaveFile (char *FileName) 






{ 

register int i; 

/* Loop counter. 



*/ 

FILE *PtrFile; 

/* File stream 

pointer. 


*/ 

char TempBuffer [LINEBUFSIZ]; 

/* Temporary local 

buffer 

for lines. 

V 

PCH FarPtr; 

/* Temporary far pointer. 


V 

unsigned BufSel; 

/* Selector of 

'TempBuf 1 . 


*/ 

if ((PtrFile = fopen (FileName, "w" 

)) == NULL) 

/* Open file. 

*/ 

return FALSE; 






FarPtr = (char far *)TempBuffer; 

/* Obtain selector 

for 1 TempBuf'. 

V 

BufSel = SELECTOROF (FarPtr) ; 






/* Write f-ile line by line, 
for (1=0; i <= LastLine; ++i) 





*7 

V 

/* First copy line into a local buffer. 




*/ 

movedata 


/* 

Block copy. 

V 

(SELECTOROF (LineTable 

i].LineAddress) 

/* 

Source 

selector. 

*/ 

OFFSETOF (LineTable [i]. 

LineAddress), 

/* 

Source 

offset. 

*/ 

BufSel, 


/* 

Target 

selector. 

*/ 

(unsigned int) TempBuffer, 

/* 

Target 

offset. 

V 

LineTable [i].LineLength); 

/* 

Length 

of line. 

V 

/* Write line to file, 
fputs (TempBuffer, PtrFile); 

} 





V 

fclose (PtrFile); 

/* Close 

f ile. 


V 

return TRUE; 






} /* end SaveFile */ 







• Figure 7.22: 

The SaveFil e function of the example program 
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If SaveFile encounters an error, it returns FALSE, and the calling 
routine displays a message box to notify the user that the file cannot be 
saved. After the user has dismissed the message box by selecting the Ok 
button, the Save routine immediately returns. Therefore, the user must 
reissue the menu command to make another attempt to save the file. If 
SaveFile is successful, it returns TRUE, and the calling routine resets 
the Modified flag to 0 and returns. 

Note that the Save routine is also invoked through messages sent by 
the New routine of the Command function (described earlier in the 
chapter), and by the Quit function. The current version of the Quit 
function checks the Modified flag before terminating the program. If 
the file buffer contains unsaved data, the function displays a message 
box and sends an ID_SAVE message if the user chooses to save the file. 
The code for performing these steps is the same as that in the New 
routine, listed and described in the previous section. 


The Exit Command 

When the user selects the Exit item of the File submenu, the sys¬ 
tem sends a WM_COMMAND message with the ID_EXIT command 
code. The routine that processes this message terminates the program 
by calling the Quit function. Note that this menu item provides an alter¬ 
native to the Close item on the system menu (which generates a 
WM_QUIT message that terminates the message-processing loop in the 
function main). 


The Insert/Overwrite Mode Command 

When the user selects the Insert item of the Options submenu or 
presses the Ins accelerator key, the system generates a WM_COM- 
MAND message with the IDJNSERT code. (Note that this item is 
labeled either "Overwrite Mode" or "Insert Mode," depending upon 
the current state of the Insert flag.) The routine that handles this mes¬ 
sage simply toggles the current state of the Insert flag, as follows: 


Insert A = 1; 
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Note that this statement was formerly located in the VKJNSERT 
branch of the VirtKey function (which processes WM_CHAR messages 
that have valid virtual-key codes). However, because the Ins key is cur¬ 
rently defined as an accelerator, it causes the system to generate a 
WM_COMMAND message rather than a WM_CHAR message. 


• ENHANCEMENTS 

This section offers two suggestions for improving the file-saving 
routine, SaveFile, described earlier in this chapter. 

When SaveFile writes a file, it simply overwrites the previous version 
of this file on the disk. The first enhancement would be to modify this func¬ 
tion so that it maintains a backup copy of the prior version of the file that is 
being saved. For example, if the file is named MEMO.TXT, you could 
maintain a backup copy through the following steps: 

1. If the file MEMO.BAK exists in the same directory where the file 
is being saved, it should be deleted (you can use the C function 
unlink or remove, or the OS/2 service DosDelete). 

2. If the file MEMO.TXT exists in the same directory where the file 
is being saved, it should be renamed to MEMO.BAK (you can 
use the C function rename, or the OS/2 service DosMove). 

3. Write the current contents of the buffer to a neve file named 
MEMO.TXT. 

A second possible enhancement would be to write the data to the file 
using the basic OS/2 services DosOpen, DosWrite, and DosClose. The 
current version of SaveFile uses the C functions fopen, fputs, and 
fclose for the sake of simplicity and to maintain consistency with the 
function ReadFile. The problem with the C function fputs, however, is 
that in the small data memory model used by the example program, the 
string address passed as the first parameter is a near pointer (that is, it 
contains only the address offset), and the function assumes that the 
string resides in the automatic data segment. The data in the heap, how¬ 
ever, are located in a separate segment and must be addressed with far 
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pointers. Accordingly, SaveFile must copy each file line into a local 
buffer before writing the line with fputs. 

Because the OS/2 function DosWrite accepts a far pointer to the 
source buffer, you can write the data directly from the heap to the file 
without an intermediate copy operation. Note, however, that you will 
have to insert a carriage-return character (ASCII 13) at the end of each 
line, since the lines stored in the heap contain only a newline character 
(An 7 , or ASCII 10). (C functions such as fputs automatically translate 
the newline character to a newline/carriage-return pair if the file was 
opened in text mode.) 


• CONCLUSION 

The next, and final, complete listing of the example program is 
provide in Figure 8.38, at the end of Chapter 8, together with a MAKE 
file and the required definition, resource, and header files. 

This chapter has added a complete menu and set of accelerator keys 
to the example program, and several of the menu commands have been 
fully implemented. For many of these commands, however, the pro¬ 
gram must provide additional information to the user and solicit the 
user's responses. For example, the Open command of the File submenu 
should display a list of files on the disk and allow the user to enter a file 
name. Such interaction with the user is easily accomplished through the 
medium of dialog boxes, which are the topic of the next chapter. 
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M any of the commands listed in the Presentation Manager 
menu presented in the previous chapter require addi¬ 
tional interaction with the user. The text for each of these 
• JL JL commands is followed by an ellipsis (...), indicating that 
the program must elicit further information before it can execute the 
command. This information is obtained through the dialog boxes de¬ 
scribed in this chapter. A dialog box is a window managed by a system 
procedure that contains an organized collection of child control win¬ 
dows, such as text strings, edit fields, and push buttons; the child control 
windows are used to display data and obtain information from the user. 
The dialog boxes employed by the example program are displayed 
when the user selects the related menu item, and they are removed when 
the user dismisses them. 

In this chapter, you will learn how to design a dialog box using the 
Dialog Box Editor; you will learn how to display a dialog box from 
the client window procedure; and you will learn how to write a proce¬ 
dure to process the messages that are sent to a dialog box. The complete 
listing of the current version of the example program is given in Figure 
8.38, at the end of the chapter, accompanied by the other files needed to 
build the executable program. 


• CREATING A DIALOG BOX 

This section describes how to design a dialog box and how to dis¬ 
play a dialog box from the client window procedure; the next main sec¬ 
tion discusses how to manage a dialog box once it has already been 
displayed. 

When you request the system to display a dialog box, you must 
supply a template, which is a collection of data describing the dimen¬ 
sions and styles of the dialog box and all the child control windows that 
it contains. You can furnish these data in the form of a Presentation 
Manager resource, in the same manner that you supply the data re¬ 
quired to create menus and accelerator tables. As described in the pre¬ 
vious chapter, the first step in creating resource data is to define these 
data in a resource script, which is then translated into binary format 
and inserted into the executable file using the resource compiler. 
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The resource script used to create the dialog boxes for the example 
program is listed in Figure 8.1. Just as a menu is defined following the 
keyword MENU and an accelerator table definition follows the keyword 
ACCELTABLE, each dialog template definition is labeled with the 
keyword DLGTEMPLATE. Note that you must define a separate 
resource for each dialog box; as you can see in Figure 8.1, the resource 
script defines five dialog boxes. 

Fortunately you never have to create a resource script such as the one 
in Figure 8.1. Rather, you can generate the script file using the Dialog 
Box Editor. The Dialog Box Editor is a Presentation Manager program 
that allows you to interactively create one or more dialog boxes; once 
you have designed the dialog boxes, you can use this utility to automat¬ 
ically generate a resource script that you can subsequently process with 
the resource compiler (the script in Figure 8.1 was generated by the 
Dialog Box Editor). 

Each of the dialog templates in Figure 8.1 contains a large and con¬ 
fusing collection of fields that specify the dimensions, locations, iden¬ 
tifiers, and attributes for both the dialog box and its child control 
windows. Using the Dialog Box Editor, however, you can easily select 
all dialog box objects and their attributes directly from program menus. 
Also, you can specify dimensions and locations by directly moving and 
resizing objects on the screen using the mouse, rather than by supplying 
numeric values. Accordingly, instead of describing the individual fields 
and identifiers of the script file, this section explains how to create a 
dialog box template through the Dialog Box Editor. Following a general 
description of using this utility, the section illustrates each of the dialog 
boxes employed by the example program and lists the options that were 
selected from the Dialog Box Editor to create these dialog boxes. 


Using the Dialog Box Editor 

The Dialog Box Editor, DLGBOX.EXE, is a Presentation Manager 
application that provides a menu, dialog boxes, a mouse interface, and 
a context-sensitive help facility. The window display that you see when 
you first start this utility is illustrated in Figure 8.2. 

The following are the general steps for using the Dialog Box Editor to 
design one or more dialog boxes, and to generate the corresponding 



Figure 8.1 

Dialog box resource script generated by the Dialog Box Editor. 


DLGTEMPLATE 2 57 LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG 257, 69, 37, 180, 74, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WSSAVEBITS 

BEGIN 

CONTROL "Save File As:", -1, 3, 50, 63, 8, WC_STATIC, 

SS TEXT | DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 

CONTROL ""7 257, 5, 31, 170, 13, WC_ENTRYFIELD, ES_LEFT | ES_AUTOSCROLL 
ES_MARGIN | WS_TABSTOP | WS_VISIBLE 

CONTROL "Current Directory:", 258, 3, 61, 174, 11, WC_STATIC, SS_TEXT | 
DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 

CONTROL "Esc=Cancel", 2, 99, 7, 56, 16, WC_BUTTON, BS_PUSHBUTTON | 
WS_VISIBLE 

CONTROL "Save", 1, 25, 8, 53, 14, WC_BUTTON, BS_PUSHBUTTON | BS_DEFAULT 
WS_TABSTOP | WSJVISIBLE 

END 

END 

DLGTEMPLATE 258 LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "", 258, 71, 43, 182, 53, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL 258, 37, 35, 141, 10, WC_ENTRYFIELD, ES_LEFT | 

ES_AUTOSCROLL | ES_MARGIN | WS_TABSTOP | WS_VISIBLE 

CONTROL "Esc=Cancel", 2, 105, 9, 60, 13, WC_BUTTON, BS_PUSHBUTTON | 
WSJVISIBLE 

CONTROL "Find", 1, 21, 9, 53, 13, WC_BUTTON, BS_PUSHBUTTON | BS_DEFAULT 
WS_TABSTOP | WS_VISIBLE 

CONTROL "Find:", -1, 6, 35, 23, 9, WC_STATIC, SS_TEXT | DT_LEFT | 

DT_TOP | WS_GROUP | WSJVISIBLE 


DLGTEMPLATE 259 LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "", 259, 90, 51, 147, 52, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "Go to Line Number:", -1, 3, 33, 86, 10, WC_STATIC, 

SSJTEXT | DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "", 259, 96, 35, 45, 7, WC_ENTRYFIELD, ES_LEFT | ES_AUTOSCROLL 
ES_MARGIN | WS_TABSTOP | WS_VISIBLE 
CONTROL "Esc=Cancel", 2, 77, 11, 61, 14, WC_BUTTON, BS_PUSHBUTTON | 
WSJVISIBLE 

CONTROL "Go to Line", 1, 9, 12, 52, 12, WC_BUTTON, BSJPUSHBUTTON | 

BS_DEFAULT | WS_TABSTOP | WS_VISIBLE 


® Figure 8.1: 

Resource script defining the dialog templates for the example program 







END 


DLGTEMPLATE 260 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN 

DIALOG ""260, 74, 17, 153, 123, FS_NOBYTEALIGN | FS_DLGBORDER | 
WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "Open File Name:", -1, 3, 108, 78, 10, WC_STATIC, 

SS_TEXT | DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "", 260, 5, 93, 132, 11, WC_ENTRYFIELD, ES_LEFT | ES_AUTOSCROLL 
ES_MARGIN | WS_TABSTOP | WS_VISIBLE 
CONTROL "", 261, 3, 67, 137, 8, WC_STATIC, SS_TEXT | DT_LEFT | 

DT_TOP | WS_GROUP | WS_VISIBLE 

CONTROL "", 262, 5, 6, 82, 57, WC_LISTBOX, WS_TABSTOP | WS_VISIBLE 
CONTROL "Open", 1, 95, 41, 57, 13, WC_BUTTON, BS_PUSHBUTTON I BS_DEFAULT 
WS_TABSTOP | WS_VISIBLE 

CONTROL "Esc=Cancel", 2, 93, 12, 59, 16, WC_BUTTON, BS PUSHBUTTON I 
WS_VISIBLE 

CONTROL "Current Directory:", -1, 3, 79, 76, 9, WC_STATIC, SS TEXT | 
DT_LEFT I DT TOP I WS GROUP I WS VISIBLE 

END 

END 

DLGTEMPLATE 256 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN 

DIALOG "", 256, 108, 32, 114, 85, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WS SAVEBITS 

BEGIN 

CONTROL "Presentation Manager", -1, 2, 67, 110, 9, WC_STATIC, 

SS_TEXT | DT_CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "Text Editor", -1, 2, 54, 109, 9, WC_STATIC, SS_TEXT | 

DT_CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "Version 1.0", -1, 3, 40, 109, 9, WC_STATIC, SS_TEXT | 

DT_CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "OK", 1, 39, 15, 34, 12, WC_BUTTON, BS_PUSHBUTTON | BS DEFAULT I 
WS_GROUP I WS TABSTOP I WS VISIBLE 

END 

END 


® Figure 8.1: 

Resource script defining the dialog templates for the example program (continued) 

resource script (note that further details are given in the next section, 
which describes each of the dialog boxes used by the example pro¬ 
gram): 

I. Select the New Dialog item of the Edit menu to begin designing 
the first dialog box. The editor will subsequently request an iden¬ 
tifier (through one of its own dialog boxes); you should assign 
each dialog box a unique identifier, since you must pass this 
value to the system to display a specific dialog box from your 
program. 
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2o The new dialog box appears within the Dialog Box Editor win¬ 
dow, which simulates the owner of the dialog box. You can move 
the dialog box to the desired location relative to this window by 
dragging it with the mouse pointer. Note that when the dialog 
box is ultimately displayed by your program, it will appear at 
the same relative position with respect to the lower left corner of 
its owner, which is normally the client window. 

3. When you click the mouse within the dialog box, a thick sizing 
border will be drawn around its edges. The object currently sur¬ 
rounded by this border is known as the selected object, and you 
can adjust the dialog box to the desired size by manipulating the 
edges of this border with the mouse in the same manner that 
you resize a standard Presentation Manager window. 

4. Select the Styles item of the Edit menu to assign or modify the 
dialog box styles (the styles chosen for each of the dialog boxes 
of the example program are described in the next section). 

5. Add controls to the dialog window (such as push buttons, 
text strings, and edit fields) by selecting each control from the 



File Include Edit Control Options Exit 


Mode: Work 


Selected Item Status 


l«.y). 

Icx.cy) 
Relative to 
Control 
ID Value 


Dialog Box Editor: [(Untitled)] [(Untitled)] 


• Figure 8.2: 

The Dialog Box Editor 
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Control menu. Use the mouse to drag a new control to the 
desired location within the dialog window. 

60 When you release the mouse button after dragging a control to 
the desired location, the editor will automatically display one of 
its own dialog boxes; you must enter an identifier for the control, 
and you can optionally add or eliminate control styles. 

7„ The new control will initially be the selected object, and will 
therefore be surrounded by a thick sizing border. You can use 
this border to adjust the size of the control in the same manner 
that you adjusted the size of the dialog box itself. 

8. At any time, you can select a control (or the entire dialog box) by 
simply clicking the mouse within its borders. Once you have 
selected an item, you can move it or adjust its size using the 
sizing border; you can also alter its identifier or styles by choos¬ 
ing the Styles item of the Edit menu. 

9. When you have completed designing a given dialog box, you 
can create another one through the New Dialog Box item of the 
Edit menu. 

10. When you have finished the last dialog box, you can save your 
data through the File menu, specifying the name of a resource 
file. The editor not only writes a resource file (with the .RES ex¬ 
tension), but more importantly, it generates a resource script file 
(with the .DLG extension). For example, if you enter the name 
APP, the editor will generate the resource file APP.RES, and the 
resource script APP.DLG (similar to the one in Figure 8.1). 

Once you have generated a resource script using the Dialog Box 
Editor, you can convert this file to binary format and insert the data into 
the executable program, as described in Chapter 7. Since the current 
version of the example program also defines resources for a menu and 
an accelerator, the script for the dialog boxes is included within the 
general resource script (Figure 8.36, listed at the end of the chapter), 
using the following statement: 


rcinclude FIGS 35.DLG 
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This statement assumes that the script file generated by the Dialog 
Box Editor is FIG8_35.DLG. When the resource compiler encounters 
this statement, it reads and processes the dialog box script file and 
adds the dialog box templates to the collection of resources in the 
.RES file that will ultimately be inserted into the executable program 
file. (Note that the .RES resource file generated directly by the Dialog 
Box Editor, which initially would contain only dialog box resources, 
is not the one loaded into the .EXE file of the example program. 
However, you must save this file if you want to add, remove, or 
modify dialog box definitions, since the current version of the Dialog 
Box Editor reads in the .RES file rather than the .DLG file when you 
specify an existing file name.) For details, see the general resource 
file (Figure 8.36), the dialog resource script (Figure 8.35), and the 
MAKE file (Figure 8.33) listed at the end of the chapter. 

Once you have designed the collection of dialog boxes and have 
placed the dialog box templates within resource segments in the ex¬ 
ecutable file, you can display any of these dialog boxes and use it to col¬ 
lect data from the user. Before explaining how to display and manage 
dialog boxes, however, the following section describes each of the 
dialog boxes used within the example program so that you will be able 
to create them; the following section also serves to describe many of the 
specific control windows and styles that you can choose from the Dia¬ 
log Box Editor. 


The Program Dialog Boxes 

This section illustrates each of the dialog boxes designed using the 
Dialog Box Editor and displayed by the example program. These dialog 
boxes use only a subset of the large number of control windows, op¬ 
tions, and styles that you can select through the Dialog Box Editor. You 
can learn about the other features by experimenting with the Dialog 
Box Editor and using its help facility, and by referring to the technical 
documentation. 

Note that the tables given in this section list the identifier for each 
dialog window and each child control window; these values are as¬ 
signed when the objects are created in the Dialog Box Editor. Some of 
the identifiers must be used within the program to reference the cor¬ 
responding objects; such identifiers are given values beginning with 
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256, and corresponding constants are defined for these identifiers to 
simplify using them within the C program. The constants are defined in 
the program header file (Figure 8.37, at the end of the chapter), which is 
included in the C source code of Figure 8.38. In contrast, the identifier 
-1 is assigned to objects that do not need to be referenced within the 
program (such as text controls containing strings that are never 
changed). 

The About Dialog Box 

The About dialog box, which is displayed in response to the About 
item of the File menu, serves to briefly identify and describe the pro¬ 
gram. This dialog box is illustrated in Figure 8.3, and its features are 
summarized in Table 8.1. The dialog box contains three control windows 
that simply display text, and a single push button that is used to dismiss 
the dialog box. 

The first column in Table 8.1 identifies each object according to the labels 
used in Figure 8.3. The second column describes the objects; note that the 
first object is the dialog window itself, and the other objects are child con¬ 
trol windows that are selected from the Control menu of the Dialog Box 
Editor (the descriptions are the same as those listed in the Control menu). 



® Figure 83: 

The About dialog box 
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The third field gives the numeric identifier, and the corresponding con¬ 
stant if one has been defined (ID_ABOUTDLG is defined in the pro¬ 
gram header file, listed in Figure 8.37, and DID JDK is defined in the 
system header file PMWIN.H). 

The final column lists all styles, features, or options that were 
selected through the Styles item of the Dialog Box Editor Edit menu. 
These styles are given exactly as they appear in the Dialog Box Editor. 
For example, the first text control (labeled 1, and containing the string 
"Presentation Manager") was defined as shown in Figure 8.4. 


e Table 8.1: Features of the About Dialog Box 


Label in 
Figure 8.3 

Type of 

Object 

ID of 

Object 

Styles/Features/ 

Options 

0 

Dialog Box 

256 

(ID_ABOUT- 

DLG) 

Options 

Dialog Frame 

1 

Text Control 

-1 

Basic Styles 

Text 

Text Styles 

Horiz. Centered 
Top Aligned 

2 

Text Control 

-1 

Basic Styles 

Text 

Text Styles 

Horiz. Centered 
Top Aligned 

3 

Text Control 

-1 

Basic Styles 

Text 

Text Styles 

Horiz. Centered 
Top Aligned 

4 

Push-Button 

Control 

1 (DID_OK) 

Types 

Push Button 
Options 

Default 
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As you can see from Table 8.1, the About dialog box is given a dialog 
frame, which is the standard thin, double-line border normally used for 
dialog boxes. Note that this is not a wide sizing border, and therefore 
the user cannot resize the dialog box. Also, since the dialog box is not 
given a title bar, the user cannot move it on the screen. The dialog box 
identifier, 256 (ID_ABOUTDLG), will be passed to the system when the 
program displays the dialog box. 

The three text controls serve to display static text strings. These controls 
are assigned styles so that the text they display is aligned at the top of the 
control and is horizontally centered. Since these three objects are not 
manipulated by the program, they are given identification values of -1. 

Finally, the push-button control is specified as a default push button. 
A default push button is given a thicker border than a normal push but¬ 
ton; also, if the user presses the Enter key, the system sends a message 
bearing the identifier of the default push button. (If a dialog box con¬ 
tains several push buttons, only one should be designated as default.) 
As you will see, the system also sends a message accompanied by the ID 
of this push button if the user clicks the mouse button with the pointer 
within its borders. The user can therefore dismiss the About box either 
by pressing Enter or by clicking on the button; the program also allows 


Figure 8.4: 

The definition of the first text control in the About dialog box 
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the user to remove the dialog box by pressing the Esc key. The push but¬ 
ton is assigned the identifier DID_OK, which is defined as 1 in the sys¬ 
tem header file PMWIN.H and is the standard value used for a default 
push button. 


The Find Dialog Box 

The Find dialog box is activated through the Find item of the 
Search menu, and allows the user to enter a string, which the program 
will attempt to find within the file. The dialog box is illustrated in Fig¬ 
ure 8.5, and its features are listed in Table 8.2. 

This dialog box contains an edit control (label 2), which allows the 
user to enter a string and to perform normal editing operations, such as 
deleting and backspacing over characters, and moving the cursor with 
the arrow keys. The edit control is left-aligned, meaning that characters 
are entered beginning at the left edge of the control; it is also assigned 
the auto horizontal scroll style, which causes the characters to automat¬ 
ically scroll left if the user reaches the right end of the field. Finally, it is 
given a margin, which means that a box will be drawn around the entire 
edit control. 



• Figure 8.5: 

The Find dialog box 
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This dialog box is given two push buttons. The push button labeled 
"Find" is made the default push button; therefore, if the user presses the 
Enter key or clicks on this button, the system will send a message con¬ 
taining the button's ID (DID_OK). The push button labeled "Esc=Can- 
cel" is given the same ID that is sent when the user presses Esc 
(DID_CANCEL); as you will see, when the program receives a message 
with this ID, it immediately removes the dialog window without per¬ 
forming the find operation. Therefore, the user can abort the operation 
by clicking on the Esc=Cancel button or by pressing Esc. 

© Table 8.2: Features of the Find Dialog Box 


Label in 

Type of 

ID of 

Styles/Features/ 

Figure 8.5 

Object 

Object 

Options 

0 

Dialog Box 

258 (ID FIND- 
DLG) 

Styles 

Dialog Frame 

1 

Text Control 

-1 

Basic Styles 

Text 


Text Styles 
Left Aligned 
Top Aligned 


2 Edit Control 258 (ID_FIND~ Text Alignment 

EDIT) Left Aligned 

Options 

Auto Horiz. Scroll 
Margin 

3 Push-Button 1 (DID_OK) Types 

Control Push Button 

Options 

Default 


4 


Push-Button 

Control 


2 (DID_CAN- Types 
CEL) Push Button 
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The Go to Line Dialog Box 

The Go to Line dialog box is displayed through the Go to Line 
item of the Search menu. This dialog box allows the user to enter the 
target line number, or to abort the operation and return to the applica¬ 
tion. It is illustrated in Figure 8.6, and its features are summarized in 
Table 8.3. This dialog box contains the same features as the Find dialog 
box, described in the previous section. 


The Save As Dialog Box 

The Save As dialog box appears when the user chooses the Save 
As item of the File menu. This dialog box displays the current drive and 
directory and allows the user to enter the name under which the current 
file is to be saved. This dialog box is shown in Figure 8.7, and is 
described in Table 8.4. 

All of the controls and styles assigned to the Save As dialog box have 
been explained in the previous sections. Note, however, that the first 
text control (label 1) is given a unique identifier (ID_SAVEASCD), 



• Figure 8.6: 

The Go to Line dialog box 




















® Table 8.3: Features of the Go to Line Dialog Box 


Label in 

Type of 

ID of 

Styles/Features/ 

Figure 8„6 

Object 

Object 

Options 

0 

Dialog Box 

259 (ID GO- 
TODLG) 

Styles 

Dialog Frame 

1 

Text Control 

-1 

Basic Styles 

Text 

Text Styles 

Left Aligned 

Top Aligned 

2 

Edit Control 

259 (ID GO- 
TOEDIT) 

Text Alignment 

Left Aligned 
Options 

Auto Horiz. Scroll 
Margin 

3 

Push-Button 

Control 

1 (DID_OK) 

Types 

Push Button 
Options 

Default 

4 

Push-Button 

Control 

2 (DID_CAN- 
CEL) 

Types 

Push Button 
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Table 8.4: Features of the Save As Dialog Box 



rather than being assigned -1 as in the previous dialog window. A 
unique identifier is required because the control is used to display the 
current program directory, and it must therefore be accessed from 
the application. (Note that the identifier needs to be unique only among 
the identifiers belonging to the same dialog box.) 
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The Open Dialog Box 

The Open dialog box is activated when the user selects the Open 
item of the File menu; it is illustrated in Figure 8.8 and described in 
Table 8.5. 



• Figure 8.8: 

The Open dialog box 


The Open dialog box displays the current drive and directory and al¬ 
lows the user to enter the name of the file that is to be opened. In addi¬ 
tion to the controls contained in the dialog boxes described previously, 
this dialog box includes a list box. The list box displays all files that have 
a .C or .TXT extension within the current directory, and contains a verti¬ 
cal scroll bar that can be used to scroll through the list. The list box also 
displays all subdirectories (including the parent directory) belonging to 
the current directory, and the letters of all disk drives that are currently 
installed. 

If the user highlights a file name (by moving the highlight to the item 
with the arrow keys or by clicking on the item with the mouse), the pro¬ 
gram displays this name automatically in the edit control. If the user 
selects a file name by pressing Enter when the name is highlighted, or 
by double-clicking on the item, the program opens the file and removes 
the dialog box. If the user selects a directory name in the same manner 






















• Table 8.5: Features of the Open Dialog Box 


Label in 
Figure 8.8 

0 

1 

2 

3 

4 

5 

6 

7 


Type of 

ID of 

Styles/Features/ 

Object 

Object 

Options 

Dialog Box 

260 

Styles 


(ID_OPEN- 

DLG) 

Dialog Frame 

Text Control 

-1 

Basic Styles 

Text 

Text Styles 

Left Aligned 

Top Aligned 

Edit Control 

260 

Text Alignment 


(ID_OPEN- 

Left Aligned 


EDIT) 

Options 

Auto Horiz. Scroll 
Margin 

Text Control 

-1 

Basic Styles 

Text 

Text Styles 

Left Aligned 

Top Aligned 

Text Control 

261 

Basic Styles 


(ID_OPEN- 

Text 


CD) 

Text Styles 

Left Aligned 

Top Aligned 

List-Box 

262 


Control 

(ID_OPEN- 

LIST) 


Push-Button 

1 

Types 

Control 

(DID_OK) 

Push Button 
Options 

Default 

Push-Button 

2 

Types 

Control 

(DID_CAN- 

CEL) 

Push Button 
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(by pressing Enter or double-clicking), the program changes to this 
directory and displays the files contained in the new directory Finally, if 
the user similarly selects a drive letter, the program changes to this 
drive and displays the files in the current directory of the new drive. 
The list box is not assigned any styles. Note that the user can use the Tab 
key to move between the edit control, the list box, and the push buttons. 


Displaying a Dialog Box 

The menu and accelerator tables are automatically loaded at the begin¬ 
ning of the program, when the standard window is created by the call to 
WinCreateStdWindow. Since, however, a dialog window is a temporary 
object, you must explicitly load it each time you want it displayed. 

A dialog window is loaded and displayed through the Presentation 
Manager function WinDlgBox (Figure 8.9). For example, the routine 
that processes the About menu item simply calls WinDlgBox to display 
the About dialog box (illustrated in Figure 8.3), as follows: 


WinDlgBox 

(HWND_DESKTOP, /* Handle of parent window: */ 

/* desktop. */ 

hwnd, /* Handle of owner: client. */ 

AboutProc, /* Address of dialog procedure. */ 


NULL, /* Resource module: the .EXE file. */ 

ID_ABOUTDLG, /* Name ID of dialog window: About.*/ 
NULL); /* Pointer to procedure data: n/a. */ 

When the client window procedure makes this call, the system dis¬ 
plays a dialog box that conforms to the template stored as a resource in 
the .EXE file. The value NULL, passed as the fourth parameter, indicates 
that the dialog resource is located in the .EXE file, rather than in 
a dynamic-link module. Note that the dialog-box identifier passed as 
the fifth parameter (ID_ABOUTDLG) is the same value assigned to the 
dialog box within the resource script. 

The third parameter supplies the address of a dialog procedure ; as 
you will see in the next section, the dialog procedure is a function that 



WinDlgBox 


Purpose: 


Loads, displays, and processes a dialog box. 

Prototype: 


USHORT APIENTRY 

WinDlgBox 

(HWND hwndParent, 

Handle of the parent window (usually 


HWND_DESKTOP). 

HWND hwndOwner, 

Handle of the owner window (usually 
the client window). 

PFNWP pfnDlgProc, 

Address of the dialog procedure. 

HMODULE hmod, 

Handle of the module containing the 
resource for the dialog box; if the 
resource is contained in the .EXE file, 
this value should be NULL; if the 


resource is in a dynamic-link library 
file, this parameter should be assigned 
the handle returned by 

DosLoadModule. 

USHORT idDlg, 

The dialog-box identifier (that is, the 

ID assigned to the dialog box in the 
resource script). 

pvoid pCreateParams ); A pointer to dialog procedure data, or j 


NULL if no data is passed to the 
dialog procedure. 

Return Value: 


The value that the dialog procedure passes as the second 
parameter to WinDismissDlg, or DIDERROR if an error 

occurred. 


Notes: 


This function does not return until the application dialog 
procedure issues the function WinDismissDlg. 

Related Functions: 


WinDismissDlg (Figure 8.11) 


• Figure 8.9: 

The WinDlgBox Presentation Manager function 










356 Programmer's Guide to the OS/2 Presentation Manager 


you write to process the messages sent to the dialog box window. Win- 
DlgBox does not return control until the dialog procedure explicitly dis¬ 
misses it (through the function WinDismissDlg, discussed in the next 
section). While the dialog box is displayed—and the dialog procedure is 
processing the messages it is sent—the user cannot switch the focus to 
another window within the current application (such a dialog box is 
described as modal). 

The first parameter supplies the handle of the parent of the dia¬ 
log box. Since the desktop window (the entire screen, identified by 
HWND_DESKTOP) is assigned as the parent, the dialog box is a top- 
level window and can appear outside the boundaries of the 
application's standard window. The second parameter specifies that 
the owner of the dialog window is the client window; accordingly, the 
dialog box will appear in the same position relative to the lower left 
corner of the client window that it appeared relative to the simulated 
owner window in the Dialog Box Editor (that is, the coordinates for the 
dialog-box position that are written to the resource script are relative to 
the lower left corner of the owning window). Note that this chapter ex¬ 
plains only one of several methods that can be used to display a dialog 
box under the Presentation Manager. 


• MANAGING A DIALOG BOX 

Once the system loads and displays a dialog box in response to the 
WinOlgBox function, all messages sent to the dialog-box window are 
received by the dialog procedure. A dialog box is thus managed by the 
associated dialog procedure in the same way that a client window is 
managed by the client window procedure assigned to the window's 
class. A dialog procedure has the following features in common with a 
client window procedure: 

• A dialog procedure is passed the same set of parameters passed 
to a window procedure, namely: 

hwmd The handle of the dialog window 

msg The message identifier 
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mpl Message-specific information 

mp2 More message-specific information 

• A dialog procedure may process a given message and return con¬ 
trol to the system, or it may pass a message to the system for 
default processing. 

® The name of each dialog procedure must be listed under the EX¬ 
PORTS statement of the linker definition file (see Figure 8.34). 

Although a dialog procedure is quite similar to a standard window 
procedure, the following are two important differences: 

9 When a dialog window is first displayed, the dialog procedure 
receives the WM_INITDLG message (explained later) rather 
than the WM_CREATE message. 

• When you pass a message to the system for default processing 
from a dialog procedure, you must call the function WinDefDlg- 
Proc (Figure 8.10) rather than WinDefWindowProc. 

When the dialog procedure issues a return statement, control reverts 
to the Presentation Manager; the dialog box, however, remains active 
and visible, and messages continue to be sent to the dialog procedure 
(also, as mentioned previously, during this time the user is unable to 
switch the focus to another window belonging to the same application). 
To remove the dialog box, the dialog procedure must call the function 
WinDismissDlg (Figure 8.11). Once the dialog box has been removed 
by calling this function, the keyboard focus reverts to the client win¬ 
dow, and the call to WinDlgBox returns to the client window proce¬ 
dure. Note that the value you assign to the second parameter of 
WinDismissDlg is the value that is then returned by WinDlgBox. Ac¬ 
cordingly, the dialog procedure can communicate information to the client 
window procedure; for example, it can return TRUE or FALSE, indicating 
whether the user pressed the Ok push button or the Cancel push button to 
dismiss the dialog box (details are given in the following section). 

The following section describes each of the dialog procedures of the 
example program that are used to implement menu commands, and 
shows how to process a number of the messages that may be received 
by a dialog procedure. 
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WinDefDlgProc 

Purpose: 

Provides default processing for a message sent to a dialog 
procedure. 

Prototype: 

ULONG APIENTRY WinDefDlgProc 
(hwnd hwndDig, Dialog window handle. 

ushort msgid, Message identifier. 

mparam mpi , Message-specific information. 

mparam mp2 ) ; Message-specific information. 

Return Value: 

The message return data; the meaning of this value depends 
upon the message. 

Notes: 

This function is called by a dialog procedure; the four 
parameters passed to the function should be the same as the 
parameters passed to the dialog procedure. The function is 
analogous to WinDefWindowProc, called by normal win¬ 
dow procedures. 

Related Functions: 

WinDefWindowProc (Figure 2.17) 


• Figure 8.10: 

The WinDefDlgProc Presentation Manager function 
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WinDismissDlg 

Purpose: 

Removes the current dialog box and causes the function 
WinDlgBox to return control. 

Prototype: 

BOOL APIENTRY WinDismissDlg 
(hwnd hwndDlg, Dialog window handle. 

ushort usResult ); Value that is to be returned by 

WinDlgBox. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

This function hides but does not actually destroy the dialog 
box; the dialog box is subsequently destroyed when control 
reverts to the function WinDlgBox, which was originally 
used to display the dialog box. 

Related Functions: 

WinDlgBox (Figure 8.9) 


® Figure 8.11: 

The WinDismissDlg Presentation Manager function 

The Commands 

Now that the general techniques for designing, displaying, and 
managing dialog boxes have been described, this section discusses each 
of the menu commands of the example program that is implemented 
using a dialog box. Note that the dialog box for each of the following 
commands was discussed in the section on The Program Dialog Boxes, 
earlier in the chapter. 
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As described in Chapter 7, the menu commands are executed by the 
function Command, which processes the messages sent from the menu 
control. This function consists of a large switch statement that branches 
to the appropriate routine based upon the identification of the selected 
menu item. Many of these routines were already discussed in Chapter 7; 
this section discusses the routines that display dialog boxes. It also 
describes each of the dialog procedures that process messages once the 
associated dialog box has been displayed. 


The About Command 

The routine for the About menu command is located within the 
Command function of the example program, and for convenience is 
also listed in Figure 8.12. This routine is activated whenever the 
WM_COMMAND message has the identifier ID_ABOUT, indicating 
that the user has selected the About item of the File submenu. The 
routine simply calls WinDlgBox to display a dialog box and returns. 
The call to WinDlgBox was described previously, in the section on Dis¬ 
playing a Dialog Box. 

The dialog procedure for the About dialog box is named AbouitProc, 
and is listed in Figure 8.13. This function processes the WM_COM- 
MAND message (Figure 7.11), and calls WinDefOlgProc to pass all 
other messages to the system for default processing. As explained in 


case ID_ABOUT: 

/* 'About' item 'File' submenu. 

*/ 

/* Display 'About 1 box 

using a dialog box. 

*/ 

WinDlgBox 



(HWND DESKTOP, 

/* Handle of parent window; desktop. 

*/ 

hwnd, 

/* Handle of owner; client. 

*/ 

AboutProc, 

/* Dialog procedure. 

*/ 

NULL, 

/* Resource module; the .EXE file. 

*/ 

ID ABOUTDLG, 

/* Name ID of dialog window; About. 

*/ 

NULL) ? 

/* Pointer to procedure data; n/a. 

V 

return FALSE; 




® Figure 8.12: 

The routine for the About menu command 
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Chapter 7, the WM COMMAND message is accompanied by a com¬ 
mand code indicating the specific event that occurred; this value is ex¬ 
tracted using the COMMANDMSG macro, as follows: 

COMMANDMSG (&msg) ->cmd 

The AboutProc function processes two command values: DID_OK and 
DID_CANCEL. 

DID_OK is the identifier that was assigned to the Ok push button in 
the dialog resource script. Accordingly, a WM_COMMAND message 
bearing this identifier is sent whenever this button is selected. (The user 
can select the button by clicking on it with the mouse, or by pressing the 
Spacebar when the button has the focus; this button automatically has 
the focus when the dialog box is first displayed.) Note that the Ok push 


MRESULT EXPENTRY AboutProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 
/* 

Process dialog messages for the 'About' dialog box. 

V 

{ 

switch (msg) 

{ 

/*** Process WM_COMMAND messages sent by 'About' dialog box controls. 

***/ 


case WM COMMAND: 




switch (COMMANDMSG(&msg)->cmd) 

{ 

/*** user clicked on 'Ok' button or pressed Enter key. 
case DID OK: 

********/ 


/*** user clicked on 'Cancel' button or pressed Escape 
case DID_CANCEL: 

WinDismissDlg (hwnd,TRUE); 
return FALSE; 

key. 

*** / 


default: 

return FALSE; 




} 

default: 

/* Execute default processing for all other messages, 
return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 


V 


} /* end AboutProc */ 




® Figure 8.13: 

The function AboutProc of the example program 
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button was designated as the default push button (this style was 
selected from the Dialog Box Editor); therefore, the system also sends 
the identifier of this button if the user presses the Enter key 

The system sends a WM_COMMAND message with the DID_CAN- 
CEL command value whenever the user presses the Esc key (As you 
will see in the next routine, the system also sends this command if the 
user has selected a button that was assigned the value DID_CANCEL as 
its identifier; the About box, however, contains no such button.) 

If AboutProc receives either of these two command messages, it 
simply calls WinDismissDlg to remove the dialog box. Accordingly, 
the user can dismiss the dialog box by selecting the Ok button, or by 
pressing either Enter or Esc. 


The Find and Find Next Commands 

The routine that processes the Find command of the Search sub¬ 
menu is listed in Figure 8.14. This command causes the program to 
search for the first instance of the specified string that occurs in the 
file beyond the current cursor position. The routine calls WinDlgBox 
to display a dialog box, and to activate a dialog procedure that ob¬ 
tains the string from the user and searches for the string within the 
file. If the dialog procedure successfully locates the string, it moves 
the cursor just beyond the position of this string within the file. If the 
new cursor position is outside the portion of the file currently dis¬ 
played in the window, the dialog procedure returns a value of TRUE, 
indicating that the window display must be updated. In this case, the 
Find routine invalidates the entire window, and sends messages to 
update the horizontal and vertical scroll bar positions. 

The dialog procedure that manages the Find dialog box, FindProc, is 
listed in Figure 8.15. This procedure processes the same two 
WM_COMMAND messages described in the previous section. The 
DID_OK command is sent if the user selects the Find button (which was 
assigned the identifier DID_OK and is also the default push button), or 
if the user presses the Enter key. The routine processes this message by 
proceeding to search for the specified text. If, however, the routine 
receives the DID_CANCEL command, it summarily dismisses the 
dialog box without performing the search. 
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case ID_FIND: /* 'Find' item of ’Search' submenu. */ 

/* Process command through a dialog box. */ 

Result = WinDlgBox 

(HWND_DESKTOP, /* Handle of parent window: desktop. */ 

hwnd, /* Handle of owner: client. */ 

FindProc, /* Dialog procedure. */ 

NULL, /* Resource module: the .EXE file. */ 

ID_FINDDLG, /* Name ID of dialog window: Find. */ 

NULL); /* Pointer to procedure data: n/a. */ 

if (Result) /* Window needs repainting. */ 

{ 

/* Redisplay window for new position in file. */ 

WinlnvalidateRect /* Invalidate window. */ 

(hwnd, /* Handle of client window. */ 

NULL, /* Invalidate ENTIRE window. */ 

FALSE); 

WinUpdateWindow (hwnd); /* Force updating of window. */ 

WinSendMsg /* Set horizontal scroll bar position. */ 


(HHScroll, 

SBM_SETPOS, 

MPFR0M2 SHORT (FirstCol,0) , 

o) ; 

WinSendMsg /* Set vertical scroll bar position. */ 

(HVScroll, 

SBM_SETPOS, 

MPFR0M2 SHORT (TopLine, 0) , 

0) 7 

} 

return FALSE; 


case ID_FINDNEXT: /* 'Find Next' item of 'Search' submenu. */ 

/* Search for string — update cursor position if found. */ 

if (SearchBuf (FindString, SCursorLine, SCursorCol) == FALSE) 

{ 

/* String not found. */ 

WinMessageBox 

(HWND_DESKTOP, 

HFrame, 

"String not found", 

"PM Text Editor", 

0 , 

MB_OK | 

MB_ICONASTERISK) ; 

return FALSE; 

} 


Figure 8.14: 

The routines for the Find and Find Next menu commands 




/* Adjust 'TopLine' for position of found string, 
if (CursorLine < TopLine 

CursorLine >= TopLine + yWin/yCharTot) 

; 

V 

X 

TopLine = max (0,CursorLine - (yWin/yCharTot)/2); 

TopLine = min (TopLine,TopLineMax); 

Update = TRUE; 

} 


/* Adjust 'FirstCol' for position of found string, 
if (CursorCol < FirstCol | 

CursorCol >= FirstCol + xWin / xChar) 

V 

1 

FirstCol = max (0,CursorCol - (xWin/xChar)/2); 

FirstCol = min (FirstCol,FirstColMax); 

Update - TRUE; 

} 


/* Update window if necessary to display a new file position, 
if (Update) 

/ 

*/ 

i 

WinlnvalidateRect /* Invalidate whole window. 

(hwnd, 

NULL, 

FALSE); 

*/ 

WinUpdateWindow (hwnd); /* Force immediate updating. 

V 

WinSendMsg /* Adjust horizontal scroll bar. 

(HHScroll, 

SBM SETPOS, 

MPFROM2SHORT (FirstCol,0), 

°) ; 

WinSendMsg /* Adjust vertical scroll bar. 

(HVScroll, 

SBM SETPOS, 

MPFROM2SHORT (TopLine, 0), 

o) ; 

} 

*/ 

V 

/* Reposition the cursor. 

WinCreateCursor 
(hwnd, 

(CursorCol - FirstCol) * xChar, 

yWin - (CursorLine - TopLine + 1) * yCharTot, 

0 , 

V 

0, 

CURSOR SETPOS, 

NULL) ; 


return FALSE; 



© Figure 8.14: 

The routines for the Find and Find Next menu commands (continued) 








Designing Dialog Boxes 


:-;RFSni/r EXPENTRY FindProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

char Buffer [2]; /* Holds first character of entered file name. */ 

USHORT Update = FALSE; /* Flag indicates whether window update needed.*/ 

switch (msg) 

/* Process WM_COMMAND messages sent by dialog controls. *****************/ 
case WM COMMAND: 

switch (COMMANDMSG(&msg)->cmd) 

/*** user clicked on 'Find' button or pressed Enter key. ******/ 
case DID_OK: 

/* Obtain text from 'Find:' edit box. */ 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_FINDEDIT), 
sizeof (Findstring), 

FindString); 

/* If search string empty, return immediately. */ 

if (FindString [0] == '\0') 
return FALSE; 

/* Search for string. */ 

if (SearchBuf (FindString, &CursorLine, SCursorCol) == 
FALSE) 

{ 

/* Display message if string not found. */ 

WinMessageBox 

(HWND_DESKTOP, 

hwnd, /* Note: parent is dialog window*/ 

"String not found", 

"PM Text Editor", 

0, 

MB_OK | 

MB_ICONASTERISK)? 

/* Remove dialog box. */ 

WinDismissDlg (hwnd, FALSE); 
return FALSE; 

) 

/* Adjust 'TopLine' for new cursor position. */ 

if (CursorLine < TopLine || 

CursorLine >= TopLine + yWin/yCharTot) 

{ 

TopLine = max (0,CursorLine - (yWin/yCharTot)/2); 
TopLine = min (TopLine,TopLineMax); 

Update = TRUE; 

) 

/* Adjust 'FirstCol' for new cursor position. */ 


• Figure 8.15: 

The function FindProc of the example program 
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if (CursorCol < FirstCol || 

CursorCol >= FirstCol + xWin / xChar) 

{ 

FirstCol = max (0,CursorCol - (xWin/xChar)/2) ; 
FirstCol = min (FirstCol,FirstColMax); 

Update = TRUE; 

} 

/* Remove dialog box, returning flag indicating */ 

/* whether window must be updated. */ 

WinDismissDlg (hwnd, Update) ? 
return FALSE; 

/*** user clicked on 'Cancel* button or pressed Escape key. */ 
case DID_CANCEL; 

/* Remove dialog box. */ 

WinDismissDlg (hwnd,FALSE); 
return FALSE; 

default: 

return FALSE; 

} 

/*** Process WM_CONTROL messages sent by edit field. ********************/ 

case WM_CONTROL: 

switch (SH0RT1FR0MMP (mpl)) 

{ 

/*** Message sent by edit box. ********************************/ 
case ID_FINDEDIT: 

switch (SH0RT2 FROMMP (mpl)) 

{ 

/*** User altered the text. *************************/ 
case EN_CHANGE: 

/* Get new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable 'Find' button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

Buffer [0]); 
return FALSE; 
default; 

return FALSE; 

} 

default: 

return FALSE; 

) 

/*** Process WM_INITDLG message sent when dialog box first displayed. ***/ 


• Figure 8.15: 

The function FindProc of the example program (continued) 
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case WM INITDLG: 



/* Display initial value of 'FindString' in 
WinSetWindowText 

(WinWindowFromlD (hwnd,ID_FINDEDIT), 
FindString); 

edit box. 

*/ 

default: 

/* Execute default processing for all other 
return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 

messages. 

V 

} /* end FindProc */ 




@ Figure 8.15: 

The function FindProc of the example program (continued) 


If the dialog procedure receives the DID_OK command, it first calls 
the WinQueryWindowText Presentation Manager function (Figure 
8.16) to extract the string that the user entered into the edit control. This 
function call copies the string from the dialog box edit control into the 
program buffer FindString. To search for the string within the file buff¬ 
er, the routine then calls the function SeardiBuf, which belongs to the 
buffer-management module and is listed in Figure 8.17. 

SeardiBuf is passed the search string and the addresses of the vari¬ 
ables containing the current cursor row and column. If this function 
finds the string within the file buffer, it adjusts the values of the vari¬ 
ables containing the cursor position so that the cursor is positioned 
immediately after the matching string, and it returns the value TRUE. If 
the function does not find the string, it returns FALSE without alter¬ 
ing the cursor-position variables. 

If SeardiBuf returns FALSE, the dialog procedure displays a mes¬ 
sage box to inform the user that the string was not found, and then dis¬ 
misses the dialog box, passing back a code of FALSE so that the client 
procedure will not update the window display. If, however, SeardiBuf 
returns TRUE, the dialog procedure adjusts the global variables Top- 
Line and FirstCol if the new cursor position falls outside the current 
boundaries of the window. (If TopLine and FirstCol must be adjusted, 
they are given values that will place the cursor within the center of the 
window.) The routine then dismisses the dialog box, returning a code 
indicating whether the client window procedure must update the win¬ 
dow display. 





• 368 Programmer's Guide to the OS/2 Presentation Manager 


Note that the function SearchBuf may have changed the values of 
CursorCol or CursorLine. The cursor is actually placed at this new 
position by the function SetFocus, which is automatically activated 
through the WM_SETFOCUS message sent when the client window 
regains the keyboard focus after the dialog window is removed. 

In general, control windows notify their owners of significant events 
either through the WM_COMMAND message (already discussed), or 
through the WM_CONTROL message (described in Figure 8.18). The 
FindProc dialog procedure processes the WM_CONTROL message sent 


WinQueryWindowText 

Pmjfose: 

Copies the text associated with a window into a program 
buffer. 

Prototype: 

SHORT APIENTRY WinQueryWindowText 
(hwnd hwnd, Window handle. 

short cchBufferMax, Length of buffer to receive text. 
psz pszBuffer); Address of buffer to receive text. 

Return Value: 

The length of the window text copied into the buffer. 

Notes: 

This function will not copy more than ccBufferMax-1 
characters. 

Related Functions: 

WinSetWindowText (Figure 7.18) 


• Figure 8.16: 

The WinQueryWindowText Presentation Manager function 
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by the edit control window whenever the text it contains is altered (the 
text can be altered either by the user or by the program through the 
WinSetWindowText function). 

Whenever its text is modified, the edit control sends a WM_CONTROL 
message with its own identifier (ID_FINDEDIT) in the low-order word of 
mpl, and the code EN_CHANGE in the high-order word of mpl. The 
dialog procedure processes this message by obtaining the first character 
contained in the edit field (through the function WinQueryWindowText). 
It then calls WinEnableWindow (Figure 4.10) to enable the Find button 
if the string contains at least one character or to disable the button if the 
string is empty. When the Find button is disabled, its text is displayed in a 
halftone font, and the system does not send the DID_OK command when 


int SearchBuf (char *FindString, PSHORT Line, PSHORT Col) 

/ * 

Searches file buffer for string 'FindString', from position given by 
'Line' and 'Column'. If string is found, updates 'Line' and 'Col' to 
position immediately after the string in buffer, and returns TRUE. If 
string is not found, function does not update 'Line' and 'Col', and it 
returns FALSE. 

V 

{ 

register int i, j; 
char far *FPtrCh; 

FPtrCh = LineTable [*Line].LineAddress + *Col; 
i = *Line; 
for (;;) 

{ 

while (*FPtrCh) 

for (j = 0; FindString [j] == FPtrCh [j] && FindString [j]; ++j ) 

if (FindString [j] == '\0') 

{ 

*Line = i; 

*Col = FPtrCh + j - LineTable [i].LineAddress; 
return TRUE; 

} 

++FPtrCh; 

} 

if (++i > LastLine) 
return FALSE; 

FPtrCh = LineTable [i].LineAddress; 

} 

} /* end SearchBuf */ 


@ Figure 8.17: 

The function SearchBuf of the example program 
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the button is selected or the user presses Enter. Accordingly, the user 
does not attempt to search for a NULL string. 

Finally, the FindProc function processes the WM_INITDLG message 
(Figure 8.19), which is sent when the dialog box is first displayed. The 
initialization routine calls WinSetWindowText to set the text in the edit 
control to the string currently contained in FindString (which is either 
empty or contains a string from a previous execution of the Find menu 
command). 


WM_CONTROL 


Purpose: 


This message is sent by a control window to its owner to j 
report a significant event. 

Parameters: 


MPARAM mpl 


low-order word: 

Identifier of control window. 

high-order word: 

The notify code, which indicates the 
specific event; the meaning of this field 
depends upon the control window 
class. 

MPARAM mp2 

Control-specific information. 

Return Value: 


NULL. 


Notes: 


See also a similar message, WM_COMMAND (Figure 7.17). 


• Figure 818: 

The WM_CONTROL Presentation Manager message 
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WMJNITOLG 

Purpose: 

This message is sent by the system to a dialog window when 
it is first created, before it becomes visible. 

Parameters: 

mparam mpi Handle of the dialog control window that 

will receive the initial keyboard focus. 

MPARAM mp2 Pointer to an optional data structure passed 

as the last parameter to WinDlgBox. 

Return Value: 

The dialog procedure should return TRUE if it has assigned 
the focus to a control window other than that given in mpl 
(by calling WinSetFocus; this would be done to alter the con¬ 
trol that receives the initial keyboard focus). The procedure 
should return FALSE if it has not changed the focus. 

Notes: 

This message allows the dialog procedure to perform in¬ 
itialization tasks. 


• Figure 8.19: 

The WMJNITDLG Presentation Manager message 

The Find Next Command 

The routine that processes the Find Next command of the Search 
submenu is listed in Figure 8.14, following the code that processes 
the Find command. This routine searches for the next occurrence of the 
string that was specified by the most recent activation of the Find com¬ 
mand. Since FindString already contains a value, this routine does not 
display a dialog box; it is described here, however, because it is closely 
related to the Find routine. 

The code for the Find Next command performs the same sequence 
of steps employed by the Find routine to search for the string and to 
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update the window display. Note, however, that the function Win- 
CreateCursor is called to explicitly reposition the cursor; this step is 
necessary because the routine does not display a dialog box, and there¬ 
fore the SetFocus function is not automatically invoked as the focus is 
passed from the dialog window back to the client window. 


The Go to Line Command 

The code that processes the Go to Line menu item is listed in Fig¬ 
ure 8.20. This command moves the cursor to the first column of the 


case ID_GOTOLINE: /* ’Go to Line’ item of ’Search’ submenu. */ 

/* Process command through a dialog box. **********************/ 


Result = WinDlgBox /* Display dialog box. */ 

(HWND_DESKTOP, /* Handle of parent window: desktop. */ 

hwnd, /* Handle of owner: client. */ 

GotoProc, /* Dialog procedure. */ 

NULL, /* Resource module: the .EXE file. */ 

ID_GOTODLG, /* Name ID of dialog window: Goto. */ 

NULL); /* Pointer to procedure data: n/a. */ 

/* If command executed, force updating of entire window. */ 

if (Result) 

{ _ 

WinlnvalidateRect /* Invalidate entire window. */ 

(hwnd, 

NULL, 

FALSE); 

WinUpdateWindow (hwnd); /* Force window update. */ 

WinSendMsg /* Set horizontal scroll bar position. */ 

(HHScroll, 

SBM_SETPOS, 

MPFROM2 SHORT (FirstCol,0) , 

o) ; 


WinSendMsg /* Set vertical scroll bar position. */ 

(HVScroll, 

SBM_SETPOS, 

MPFROM2SHORT (TopLine, 0) , 

o); 


return FALSE; 


© Figure 8.20: 

The routine for the Go to Line menu command 
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specified line number. Most of the processing for this command occurs 
within the dialog procedure, which returns a value of TRUE if the com¬ 
mand was executed (the user selected the Go to Line push button), or 
FALSE if the command was aborted (the user selected the Cancel but¬ 
ton). If the command was executed, as indicated by a TRUE return 
value, the routine invalidates the entire window to force the Paint func¬ 
tion to display the appropriate data for the new file position. 

The dialog procedure for this command is named GotoProc, and it is 
listed in Figure 8.21. This function is quite similar to the dialog proce¬ 
dure for the Find command, discussed in the previous section. If the 
procedure receives a WM_COMMAND message with the DID_OK 
command, it extracts the text from the edit control and calls the C 
library function atoi to convert the string to a numeric value. If the 
resulting line number is valid (that is, greater than 0), it is first decre¬ 
mented because the user counts lines beginning with 1, whereas the 
program enumerates lines beginning with 0. If the number is invalid, 
the function simply returns, which terminates processing of the current 
message but causes the dialog box to remain active. 

The routine next sets the global variable CursorLine to the newly ob¬ 
tained line-number value, and adjusts TopLine so that the line contain¬ 
ing the cursor is displayed halfway down the screen. Finally, CursorCol 
and FirstCol are set so that the first column will be visible and will con¬ 
tain the cursor, and the dialog box is dismissed, returning a value of 
TRUE to force the client window procedure to update the window dis¬ 
play. (Note that when the dialog box is removed, the SetFocus function 
performs the actual repositioning of the cursor.) 

In the same manner as the FindProc function, GotoProc processes 
the WM_CONTROL message sent by the edit control when its text is 
changed. This routine enables the Go to Line push button only if the 
edit control contains at least one character. 

Finally, FindProc processes the WMJNITDLG message. This routine 
calls WinEnableWindow to initially disable the Go to Line button, since 
the edit control does not yet contain text. 
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MRESULT EXPENTRY GotoProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2 ) 


char NumberBuf [33] 
char Buffer [2] ; 
SHORT LineNumber; 



switch (msg) 

/ 



/ *** 

Process WM_COMMAND messages sent by dialog controls. ***************/ 


case WM COMMAND: 



switch ( COMMANDMSG ( &msg)->cmd) 



/*** User 
case 

clicked on 'Go to' button or pressed Enter key. *****/ I 
DID_OK: 



/* Obtain text from 'Go to Line' edit box. 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID GOTOEDIT), 
sizeof (NumberBuf), 

NumberBuf); 

V 



/* Convert to numeric value and continue if > 0. 
LineNumber = atoi (NumberBuf); 
if (LineNumber <= 0) 
return FALSE; 

*/ 



/* Set global cursor and window position variables. 
— LineNumber; 

CursorLine = min (LastLine,LineNumber) ; 

TopLine = max ( 0,CursorLine - (yWin/yCharTot)/2 ); 
TopLine = min (TopLine,TopLineMax) ; 

CursorCol = FirstCol =0; 

*/ 



/* Remove dialog box. 

WinDismissDlg (hwnd, TRUE) ; 
return FALSE; 

*/ 


/*** user 
case 

clicked on 'Cancel' button or pressed Escape key. 
DID__CANCEL: 

V 



/* Remove dialog box. 

WinDismissDlg (hwnd,FALSE) ; 
return FALSE; 

*/ 


default : 

return FALSE; 

} 


/*** 

Process WM_CONTROL messages sent by edit field. ********************/ 


case WM_CONTROL: 



switch ( SH0RT1FR0MMP (mpl)) 



® Figure 8.21: 

The function GotoProc of the example program 
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{ 

case ID_GOTOEDIT: 

switch (SH0RT2FR0MMP (mpl)) 

/*** user altered the text. *************************/ 
case EN_CHANGE: 

/* Get new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable ’Go to' button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

Buffer [0])? 
return FALSE; 
default; 

return FALSE; 

} 

default; 

return FALSE; 


/*** Process WM_INITDLG message sent when dialog box first displayed. ***/ 
case WM_INITDLG: 

/* initially disable 'Go to' button (until text entered). */ 

WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

FALSE); 
return FALSE; 

default; 

return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 

} /* end GotoProc */ 


® Figure 821: 

The function GotoProc of the example program (continued) 


The Save As Command 

The Save As command of the File submenu saves the current file 
under a name that is specified by the user; this command can be used 
either to change the file name or to assign a name to an untitled file when 
performing the save operation. The routine that executes this command is 
invoked when the user selects the Save As item from the File menu, or 
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when control drops through from the Save routine (the Save routine 
precedes the Save As routine, and allows control to pass to the Save As 
routine if the file is currently unnamed). The routine serves only to ac¬ 
tivate the appropriate dialog box, and is listed in Figure 8.22. 

The dialog procedure for the Save As command, SaveAsProc, is 
listed in Figure 8.23. When the user selects the Save dialog button, this 
function extracts the contents of the edit control, and—if the string is 
not empty—it calls the function SaveFile (described in Chapter 7). If 
SaveFile returns TRUE, indicating that it successfully saved the file 
under the new name, the fully qualified version of this name is stored in 
the global variable FileName, the new name is displayed in the title bar 
(by calling ShowFileName), and the Modified flag is reset to 0. If Save¬ 
File returns FALSE, the procedure displays a message box to inform the 
user that the file could not be saved. Whether or not the save operation 
was successful, the dialog box is dismissed. 

SaveAsProc also processes the WM_CONTROL message that is sent 
whenever the text in the edit control is modified. The routine that 
processes this message performs the same tasks as the routines belong¬ 
ing to the dialog procedures that have already been described. 

Finally, the SaveAsProc function processes the WM_INITDLG mes¬ 
sage to initialize the dialog box. The initialization routine first sends 
the message EM_SETTEXTLIMIT (Figure 8.24) to the edit control. This 
message is sent to an edit control of a dialog box to set the maximum 
number of characters that can be entered into the control (either by the 
user or by the program when it calls WinSetWindowText; the default 
number of characters is 32). The maximum is set to the value PATH- 
LENGTH (currently 128), so that the edit control can accommodate a 


case ID_SAVEAS: 


/* 'Save As' item of 'File' submenu. */ 


/* Process message using 
WinDlgBox 

(HWND_DESKTQP, 
hwnd, 

SaveasProc, 

NULL, 

ID_SAVEASDLG, 

NULL) ; 


a dialog box. 

/* Handle of parent window: desktop. 
/* Handle of owner: client. 

/* Dialog procedure. 

/* Resource module: the .EXE file. 
/* Name ID of dialog window: Saveas 
/* Pointer to procedure data: n/a. 


*/ 

*/ 

*/ 

*/ 

*/ 

V 

*/ 


return FALSE; 


© Figure 8.22: 

The routine for the Save As menu command 
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MRESULT EXPENTRY SaveasProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


/* 

*/ 


Processes dialog messages for the 'Save As' dialog box. 


char FilePath [PATHLENGTH]; /* Holds file path. 

char CurDir [PATHLENGTH + 22]; /* Holds contents of 'Current 

char Buffer [2]; /* Holds first character of entered 


*/ 

Directory'.*/ 
file name. */ 


switch (msg) 

/*** process WM_COMMAND messages sent by dialog controls. 




case WM COMMAND: 


switch (COMMANDMSG(&msg)->cmd) 

/*** user clicked on 'Save' button or pressed Enter key. ******/ 
case DID_OK: 

/* Obtain text from 'Save As' edit box. */ 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_SAVEASEDIT), 
sizeof (FilePath), 

FilePath); 

/* if path string not empty, save file/remove dialog*/ 
if (FilePath [0]) 

( 

/* Save under the new name. */ 

if (SaveFile (FilePath) == FALSE) 

/* Display error message if save failed. */ 
WinMessageBox 


(HWND_DESKTOP, 

hwnd, 

"Error — Cannot Save File", 

"PM Text Editor", 


0, 

MB OK | 

MB_ICONASTERISK); 

else 


{ 

/* Store fully qualified path name. 
Qualify (FilePath, FileName); 

V 

/* Display the new name in title bar. 
ShowFileName (); 

V 

/* Reset 'Modified' flag. 

Modified = 0; 

} 

*/ 

/* Remove dialog box. 

WinDismissDlg (hwnd, TRUE); 

V 


© Figure 8.23: 

The function SaveAsProc of the example program 
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return FALSE; 

} 

return FALSE? 

/*** user clicked on ’Cancel’ button or pressed Escape key. ***/ 
case DID_CANCEL: 

/* Remove the dialog box. */ 

WinDismissDlg (hwnd,TRUE); 
return FALSE; 

default: 

return FALSE; 

} 

/*** Process WM_CONTROL messages sent by edit box. **********************/ 

case WM_CONTROL: 

switch (SH0RT1FR0MMP (mpl)) 

{ 

/*** Message sent by edit box. ********************************/ 
case ID_SAVEASEDIT: 

switch (SH0RT2 FROMMP (mpl)) 

{ 

/*** User altered the text. *************************/ 
case EN_CHANGE: 

/* Get new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable ’Save’ button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID OK), 

Buffer [0]); “ 

return FALSE; 
default: 

return FALSE; 

} 

default: 

return FALSE; 

} 

/*** Process WM_INITDLG message sent when dialog box first displayed. ** 
case WM_INITDLG: 

/* Expand text limit in edit box to full file path lenqth. */ 
WmSendDlgltemMsg 
(hwnd, 

ID_SAVEASEDIT, 

EM_SETTEXTLIMIT, 

MPFR0M2 SHORT (PATHLENGTH,0) 

0 ) ; 


• Figure 823: 

The function SaveAsProc of the example program (continued) 
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/* Initially disable the 'Save' button until text is entered. 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

FALSE); 

V 


/* obtain current directory path. 

GetPath (FilePath, sizeof (FilePath)); 

V 


/* Format string for 'Current Directory' field, 
sprintf (CurDir,"Current Directory: %s",FilePath); 

V 


/* Display string in 'Current Directory' field. 
WinSetWindowText 

(WinWindowFromID (hwnd, ID SAVEASCD), /* ID of 

/* 'Current Directory' field. 
CurDir); /* String to display. 

V 

V 
*/ 

*/ 


return FALSE; 


default: 

/* Execute default processing for all other messages, 
return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 

V 

} /* end 

SaveasProc */ 


® Figure 8.23: 

The function SaveAsProc of the example program (continued) 


full file path specification. Note that the message is sent using the func¬ 
tion WinSendDlgltemMsg (Figure 8.25) rather that the usual Win- 
SendMsg function. This function allows you to send a message to a 
dialog control window that is specified according to its identifier and 
the handle of its parent, rather than by its own handle (which is not nor¬ 
mally known). The call to WinSendDlgltemMsg is slightly simpler 
than the following equivalent call to WinSendMsg: 

WinSendMsg 

(WinWindowFromID (hwnd,ID_SAVEASEDIT), 

EM_SETTEXTLXMIT, 

MPFROM2SHORT (PATHLENGTH,0), 

0 ); 

The initialization routine next calls WinEnableWindow to disable the 
Save push button, since the edit control initially contains no text. Final¬ 
ly, it writes the current disk drive and directory path specification to the 
text control located above the dialog box, identified as ID_SAVEASCD. 
As usual, the text is assigned by calling WinSetWindowText. A string 
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containing the current drive and directory is obtained by calling the 
utility function GetPath (listed in Figure 7.16 and described in Chap¬ 
ter 7). 


The Open Command 

The Open command of the File menu allows the user to open a 
new file matching a specified file name. The routine that executes this 
command is listed in Figure 8.26. This routine simply displays a dialog 
box; all of the file-opening logic resides within the dialog procedure. 

The dialog procedure for the Open dialog box is named OpenProc, 
and is listed in Figure 8.27. This function processes the messages shown 

EM_SETTEXTLIMIT 

Purpose: 

This message is sent to an edit control of a dialog box to set 
the maximum number of characters that can be entered 
into the control. 

Parameters: 

MPARAM mpl 

low-order word: The maximum number of characters, 

high-order word: 0. 

MPARAM mp2 NULL. 

Return Value: 

The edit control returns TRUE if the function was successful, 
or FALSE if an error occurred. 

Notes: 

This message sets the limit of the number of characters that 
can be entered by the user, or assigned to the edit control 
through the WinSetWindowText function. 


• Figure 8.24: 

The EM_SETTEXTLIMIT Presentation Manager message 
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in Table 8.6. Note that the first values given for mpl in the table repre¬ 
sent the low-order words passed to the dialog procedure in this 
parameter, and the second values represent the high-order words. Each 
of these messages is now discussed. 


WinSendDigltemMsg 

Purpose: 

Sends a message to a child control window within a dialog 
box; the target control window is specified by its identifier 
and the parent window handle (rather than by its own win¬ 
dow handle). 

Prototype: 

MRESULT APIENTRY WinSendDigltemMsg 

(hwnd hwndDlg, Dialog window handle. 

ushort iditem, Identifier of child control window. 
ushort msg, Message identifier. 

mparam mpl , Message parameter 1 (message-specific 

meaning). 

mparam mp2) ; Message parameter 2 (message-specific 

meaning). 

Return Value: 

The value returned by the control window procedure. 
Notes: 

This function is equivalent to calling WinSendMsg, specify¬ 
ing the handle of the child control window. 

Related Functions: 

WinSendMsg (Figure 4.8) 


9 Figure 8.25: 

The WinSendDigltemMsg Presentation Manager function 
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• Figure 8.26: 


The routine for the Open menu command 

WM_COMMAND / DID_OK 

The WM_COMMAND message with the DIDOK command 
value is sent when the user selects the Open push button or presses the 
Enter key. In response to this message, the dialog procedure first calls 
WinQueryWindowText to extract the file name entered into the edit 
control. If the file buffer contains unsaved data (which is indicated if the 
Modified flag is set to 1), the procedure gives the user the opportunity 
to save the current file before reading the new file. Note that rather than 
duplicating the code for saving the file, the routine simply sends a 
WM_COMMAND message—with an IDSAVE command code— 
directly to the client window; this is exactly the same message that is 
sent to the client when the user selects the Save item from the File sub¬ 
menu. (Note also that if the current file has not been assigned a name, 
the client window procedure will display the Save As dialog box. It is 
thus possible to display a dialog box on top of an already active dialog 
box; when the second dialog box is dismissed, the first one is uncovered 
and resumes processing.) 

Next, the procedure frees the current contents of the heap by calling 
ReleaseFile, and reads the new file by calling ReadFile. If the read 
operation fails, the program sets FileName to NULL and initializes a 
new, empty file by calling NewFile. If the read operation is successful, 
the fully qualified version of the new file name is stored in FileName. In 
either case, the file name is displayed in the title bar (ShowFileName), 
the Modified flag is reset to 0, and the window is initialized for the new 
file (InitWindow). Finally, the procedure calls WinDismissDlg to 
remove the dialog box. 
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® Table 8.6: Messages Processed by the QpenProc Dialog Procedure 


Message 

mpl Value 

Action 

WM_COMMAND 

DID_OK 

Extracts the file 
name, opens the 
new file, and dis¬ 
misses the dialog 
box 

WM_COMMAND 

DID_CANCEL 

Dismisses the 
dialog box 

WM_CONTROL 

ID_OPENEDIT 

EN_CHANGE 

Enables/disables 
the Open button 

WM_CONTROL 

IDOPENLIST 

LNJENTER 

Changes to the 
drive or direc¬ 
tory, or opens the 
file selected in 
the list box 

WM_CONTROL 

ID_OPENLIST 

LN_SELECT 

Writes the name 
of the file 
selected in the list 
box into the edit 
field 

WMJNITDLG 


Expands the text 
limit of the edit 
control; disables 
the Open push 
button; displays 
the initial direc¬ 
tory data in the 
dialog box 



MRESULT EXPENTRY OpenProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* 

Processes messages sent to 'Open' dialog box. 

*/ 

{ 

SHORT Selectlndex? /* Index of selected item in 'Open 1 list box. */ 

char Buffer [16]; /* Temporary storage for text. */ 

static char FilePath [PATHLENGTH]; /* Holds file path string. */ 

USHORT Reply; /* Response from message box. */ 

switch (msg) 

{ 

/*** process WM_COMMAND messages sent by dialog controls. ***************/ 

case WM_COMMAND: 

switch (COMMANDMSG(&msg)->cmd) 

{ 

/*** User clicked on 'Open' button or pressed Enter key 
case DID_OK: 

/* Obtain text from edit box. 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_OPENEDIT), 
sizeof (FilePath), 

FilePath); 

/* If a file name is entered, try to read the 
if (FilePath [0]) 

{ 

if (Modified) /* File is modified. 

{ 

/* Warn user and elicit response on 
/* saving file. 

Reply = WinMessageBox 
(HWND_DESKTOP, 
hwnd, 

"File Unsaved; Save?", 

"PM Text Editor", 

0, 

MB_YESNO | 

MB_ICONQUESTION); 


/* If reply is Yes, send a ’Save' menu */ 

/* message to client. */ 

if (Reply == MBID_YES) 

/* Repeat message until file */ 

/* successfully saved. */ 

while (Modified) 

WinSendMsg 

(HClient, 

WM_COMMAND, 


MPFROM2SHORT (ID_SAVE, 0), 
0L) ; 


© Figure 8.27: 

The function OpenProc of the example program 


. ****** y 
*/ 

file. */ 

*/ 

*/ 

V 
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} /* end if Modified */ 

ReleaseFile (); /* Free current heap. */ 

/* Read the new file. */ 

if (ReadFile (FilePath)) 

{ 

/* Warn user if read error occurred. */ 

WinMessageBox 

(HWND_DESKTOP, 
hwnd, 

"Error -- Cannot Read File", 

"PM Text Editor", 

0 , 

MB_OK | 

MB_ICONASTERISK); 


FileName [0] = '\0'; /* Null file name. */ 

NewFile (); /* New file instead.*/ 

} 

/* File was successfully read. */ 

else 

/* Store fully qualified path name. */ 

Qualify (FilePath, FileName); 

ShowFileName (); /* Display name in title bar. */ 
Modified =0; /* Reset modified flag. */ 

InitWindow (); /* Set window/cursor values. */ 

/* Remove the dialog box. */ 

WinDismissDlg 

(hwnd, /* Handle of dialog window. */ 

TRUE); /* Code returned by WinDlgBox. */ 

return FALSE; 

} 


return FALSE; 

/*** user clicked on 'Cancel' button or pressed Escape key. ***/ 
case DID__CANCEL: 

/* Remove the dialog box. */ 

WinDismissDlg 

(hwnd, /* Handle of dialog window. */ 

TRUE); /* Code returned by WinDlgBox. */ 

return FALSE; 

default: 

return FALSE; 

} 

/*** process WM_CONTROL messages sent by edit box or list box. **********/ 
case WM CONTROL; 


® Figure 8.27: 

The function OpenProc of the example program (continued) 
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switch (SHORT1FR0MMP (mpl)) 

{ 

/*** Message sent by edit box. ********************************/ 
case ID_OPENEDIT: 

switch (SHORT2 FROMMP (mpl)) 

{ 

/*** user altered the text. *************************/ 
case EN_CHANGE: 

/* Get the new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable 'Open 1 button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

Buffer [0]); 
return FALSE; 
default: 

return FALSE; 

} 

/*** Message sent by list box. ********************************/ 
case ID_OPENLIST: 

/* Get index of selected item. */ 

Selectlndex = (SHORT) WinSendDlgltemMsg 
(hwnd, 

ID_OPENLIST, 

LM_QUERYSELECTION, 

0L, 

0L) ; 

/* Get text belonging to selected item. */ 

WinSendDlgltemMsg 
(hwnd, 

ID_OPENLIST, 

LM_QUERYITEMTEXT, 

MPFROM2 SHORT (Selectlndex, sizeof (Buffer)) , 
MPFROMP (Buffer)); 


/* Branch on code for specific event. */ 

switch (SHORT2 FROMMP (mpl)) 

{ 

/* User pressed Enter key or double clicked. */ 
case LN_ENTER: 

/* Item is for a drive letter. */ 

if (Buffer [0] == '[' && 

Buffer [1] == ’-') 

{ 

/* Change to specified drive. */ 

DosSelectDisk (Buffer [2] - 64); 

/* Update dialog box data. */ 

InitDlg (hwnd); 

} 

/* Item is for a directory. */ 


9 Figure 8.27: 

The function OpenProc of the example program (continued) 




else if (Buffer [0] 


{ 

/* Null terminate after directory. */ 
Buffer [strlen (Buffer) - 1] = '\0'; 

/* Change to new directory. */ 

DosChDir 

(Buffer + 1, 

0L) ; 

/* Update dialog box data. */ 

InitDlg (hwnd); 

} 

/* Item is a file name. */ 

else if (Buffer [0]) 

{ 

/* Save the file by sending message. */ 
WinSendMsg 

(hwnd, /* Dialog window hand.*/ 
WM_COMMAND, /* Message ID. */ 
MPFROM2 SHORT (DID_0K,0) , 

0L) ; 

/* Remove the dialog box. */ 

WinDismissDlg (hwnd, TRUE); 
return FALSE; 

} 

return FALSE; 


/* New item is selected 
case LN_SELECT: 

(highlighted). 

*/ 

/* Null string for 

drive or directory. 

*/ 

if (Buffer [0] == 

' [') 


Buffer [0] = 

' \0' ; 


/* Place selected text in edit box. 
WinSetWindowText 

*/ 


(WinWindowFromID (hwnd,ID_OPENEDIT), 
Buffer); 
return FALSE; 


default; 

return FALSE; 

} 

default: 

return FALSE; 

} 

/*** Process WM_INITDLG message sent when dialog box first displayed. ***/ 
case WM_INITDLG: 

/* Expand text limit in edit box to full file path length. */ 
WinSendDlgltemMsg 
(hwnd, 

ID_OPENEDIT, 

EM_SETTEXTLIMIT, 


® Figure 8.27: 

The function OpenProc of the example program (continued) 
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MPFROM2 SHORT (PATHLENGTH,0) , 

o) ; 



/* Initially disable the ’Open' button until text is entered. 
WinEnableWindow 

(WinWindowFromID (hwnd, DID OK), 

FALSE); 

V 

/* Display initial directory and list 
InitDlg (hwnd); 

return FALSE; 

default: 

box data. 

V 

/* Execute default processing for all 

other messages. 

V 

return WinDefDlgProc (hwnd, msg, mpl, 

} /* end switch */ 

) /* end OpenProc */ 

mp2) ; 



• Figure 8.27: 

The function OpenProc of the example program (continued) 


WM_COMMAND / DID__CANCEL 

In response to the Cancel command, the dialog procedure simply 
calls WinDismissDlg to dismiss the dialog box. 

WM_CONTROL / ID_OPENEDIT / EN jCHANGE 

As described in previous sections, this WM_CONTROL command 
is sent whenever the text in the edit control is modified. The dialog pro¬ 
cedure enables the Open push button if this edit contains at least one 
character, and disables it if the edit text is NULL. 

WMCONTROL / ID„OPENLIST / LN_ENTER 

Before processing this WM_CONTROL command, or the one 
described in the following section, the dialog procedure obtains the text 
for the currently selected item within the list box (the selected item is 
the one that is highlighted). To obtain the text for the selected item, the 
procedure cannot simply call WinQueryWindowText. Rather, it sends 
two specific messages directly to the list box control (note that these 
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messages are sent using the WinSendDlgltemMsg function, described 
previously in the chapter). First, it sends the LM_QUERYSELECTION 
message (Figure 8.28) to obtain the index of the selected item within the 
list box; it then sends the LM_QUERYITEMTEXT message (Figure 8.29) 
to obtain the text for the item corresponding to this index (the text is 
copied into Buffer). 

The list box sends a WM_CONTROL message with the LN_ENTER 
code if the user presses the Enter key while an item in the list is high¬ 
lighted, or if the user double-clicks on an item with the mouse. Note 
that the selected list box item can be a disk drive letter (which begins 
with the characters a directory specification (which begins with 

the T character), or a file name (you will see later how these different 
types of items are formatted). If the current selection contains a disk 
drive letter, the procedure first changes to the specified drive by calling 
the DosSelectDisk OS/2 function, and then calls the function InitDlg 
to update the dialog box control that displays the current directory, and 


LM_QUERYSELECTION 

Purpose: 

This message is sent to a list box control window to obtain 
the index of the currently selected item. 

Parameters: 

MPARAM mpl 0. 

MPARAM mp2 0. 

Return Value: 

The index of the selected item. 

Notes: 

You can obtain the text for the selected item by sending the 
LM_QUERYITEMTEXT message (Figure 8.29). 


• Figure 8.28: 

The LM_QUERYSELECTION Presentation Manager message 
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LM_QUERYITEMTEXT 

Purpose: 

This message is sent to a list box control window to obtain 
the text for a specific item within the list box. 

Parameters: 

MPARAM mpl 

low-order word: The index of the item, 

high-order word: The length of the receiving buffer. 

mparam mp2 The far address of the receiving buffer. 

Return Value: 

The actual length of the item text. 

Notes: 

You can obtain the index of the item that is currently selected by 
sending the LM_QUERYSELECTION message (Figure 8.28). 


© Figure 8.29: 

The LM_QUERYITEMTEXT Presentation Manager message 

to update the contents of the list box (InitDlg is explained later, in the 
section on the WM_INITDLG message). Likewise, if the current selec¬ 
tion contains a directory specification, the procedure calls the OS/2 
function DosChDir to change to the new directory, and then calls Init¬ 
Dlg to update the dialog box data. 

Finally, if the selected item is a file name, the procedure sends itself a 
WM_COMMAND message with a DID_OK command code to cause it 
to save the file under the selected name. (You may have noticed that the 
LN_ENTER routine obtains the file name from the list box, while the 
DID_OK routine obtains the file name from the edit control. It might 
seem, therefore, that when sending this recursive message, the DID_OK 
routine would not access the correct file name. Note, however, that the 
LN_SELECT message, described next, is always sent before the 
LN_ENTER message; and, as you will see, the LN_SELECT message 
copies the selected text from the list box to the edit control.) 
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WM_CONTROL / IB^OPENLIST / LN„SELECT 

The list box sends a WM_CONTROL message with the 
LN_SELECT code whenever a new list box item is selected. An item can 
be selected by clicking on it with the mouse (which highlights the item), 
or by moving the highlight bar to the item using the arrow keys (to use 
the arrow keys, the list box must own the keyboard focus; the user can 
move the focus from one control to another with the Tab key). The 
dialog procedure responds to this message by calling WinSetWindow- 
Text to copy the selected text to the edit control. 

WMJNITDLG 

The initialization routine invoked through the WMJNITDLG 
message first sends the EM_SETTEXTLIMIT message to the edit control 
to expand its text limit to accommodate a full path specification. Next, 
it calls WinEnableWindow to initially disable the Open push button, 
and finally, it calls InitDlg (Figure 8.30) to display the required data for 
the current drive and directory. 

The InitDlg function is called when the dialog box is initialized, and 
whenever the current drive or directory changes. It performs the fol¬ 
lowing sequence of tasks: 

1. It obtains a string containing the current drive letter and direc¬ 
tory specification by calling GetPath, and displays this string in 
the text control that shows the current directory path 
(ID_OPENID). 

2. InitDlg then sends a LMJ3ELETEALL message (Figure 8.31) to 
the list box, which causes this control to clear all items that it 
contains. 

3. The function calls the OS/2 service DosQCnrDisk to obtain a 
mapping of all installed disk drives. It then adds the letter of 
each drive to the set of items displayed in the list box. An item is 
inserted into the list box by sending the LM JNSERTITEM mes¬ 
sage (Figure 8.32). Disk drive letters are surrounded by the char¬ 
acters "[-" and "-]" to distinguish them from directory and file 
names; for example, drive A is displayed as "[-A-]". Note that 
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VOID InitDlg (HWND hwnd) 

/* 

Called by 'OpenProc' to display current data in 'Current Directory' field 
and list box of 'Open' dialog box. 


register int Drive; 

USHORT DriveNumber; 

ULONG LogicalDrives; 
char Buffer [PATHLENGTH]; 
HDIR HSearch = 1; 
FILEFINDBUF FindBuf; 
USHORT FileCount = 1; 
char *PtrCh; 


/* Disk drive letter. */ 
/* Disk drive number. */ 
/* Mapping of installed drives. */ 
/* Holds file paths. */ 
/* OS/2 file search handle. */ 
/* Structure for file searches. */ 
/* Count files to find/found. */ 
/* Temporary character pointer. */ 


/*** obtain current default drive path. **************************************/ 
GetPath (Buffer, sizeof (Buffer)); 

/*** Display current drive and directory path in 'Current Directory' field. **/ 
WinSetWindowText 

(WinWindowFromID (hwnd, ID_OPENCD), /* ID of 'Current */ 

/* Directory' field. */ 

Buffer); /* Buffer containing text to display. */ 

/*** obtain current default disk and mapping of installed drives. ************/ 
DosQCurDisk 

(StDriveNumber, /* Receives number of current drive. */ 

&LogicalDrives); /* Receives mapping of installed drives. */ 

/*** clear all existing entries from the list box. ***************************/ 
WinSendDlgltemMsg /* Send message to dialog item. */ 

(hwnd, /* Handle of dialog window. */ 

ID_OPENLIST, /* ID of list box. */ 

LM_DELETEALL, /* Delete all entries. */ 

0, /* mpl: not used. */ 

0) ; /* mp2: not used. */ 

/*** Insert drive letters into list box. *************************************/ 
for (Drive = 'A'; Drive <= 'Z'; ++Drive) 

{ 

if (LogicalDrives & 1) 

{ 

sprintf (Buffer,"[-%c-]", Drive); 

WinSendDlgltemMsg /* Send message to dialog item. */ 

(hwnd, /* Handle of dialog window. */ 

ID_OPENLIST, /* ID of list box. */ 

LM_INSERTITEM, /* Insert an item. */ 

MPFROM2SHORT (LIT_SORTASCENDING, 0), /* Ascending sort */ 

/* order. */ 

MPFROMP (Buffer)); /* Address of item text. */ 

} 

LogicalDrives »= 1; 

} 

/*** Insert directories and files into list box. *****************************/ 


Figure 830: 

The function InitDlg of the example program 
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/* Find first directory or file. 
DosFindFirst 


/ 

&HSearch, / 

0x0010, / 

&FindBuf, / 

sizeof (FindBuf), / 

&FileCount, / 

0L) ; / 

/* Process each matching file, 
while (FileCount) 


/* Any name. */ 
/* Receives handle for search. */ 
/* Subdirectories and normal files. */ 
/* Receives information on matching file. */ 
/* Length of buffer to receive information*/ 
/* Count of files to find/files found. */ 
/* Reserved: must be 0. */ 


/* If match is a directory, but NOT '.', insert it in list box. */ 
if (FindBuf.attrFile & 0x0010 && 

i(FindBuf.achName [0] == && FindBuf.achName [1] == 1 \0')) 

{ 

sprintf (Buffer,"[%s]",FindBuf.achName); 

WinSendDlgltemMsg /* See above. */ 

(hwnd, 

ID_OPENLIST, 

LM_INSERTITEM, 

MPFROM2SHORT (LIT_SORTASCENDING, 0), 

MPFROMP (Buffer)); 

/* If match is a normal file, insert only if it has the .TXT or */ 
/* .C extension. */ 

else if (strcmp ((PtrCh = Extension (FindBuf.achName)),"TXT") == 0 
|| strcmp (PtrCh,"C") == 0) 

WinSendDlgltemMsg /* See above. */ 

(hwnd, 

ID_OPENLIST, 

LM_INSERTITEM, 

MPFR0M2SHORT (LIT_SORTASCENDING, 0), 

MPFROMP (FindBuf.achName)); 


/* Find NEXT matching file. 
DosFindNext 

(HSearch, /* 
&FindBuf, /* 
sizeof (FindBuf), /* 
&FileCount); /* 


/* Search handle returned by DosFindFirst.*/ 
/* Receives information on matching file. */ 
/* Length of receiving buffer. */ 
/* Returns number of matching files left. */ 


/* end InitDlg */ 


© Figure 8.30: 

The function InitDlg of the example program (continued) 
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this message is accompanied by a code indicating that the items 
should be sorted in ascending order. 

4. It then uses the OS/2 functions DosFindFirst and DosFindNext 
to obtain the name of each directory and each file within the cur¬ 
rent directory. Directory names are formatted with surrounding 
brackets (for example, the directory CODE would be formatted 
as "[CODE]"). All directory names (except ".") and all files that 
have the .C or .TXT extension are inserted into the list box. 

Note that selecting only files with the .C or .TXT extension is an ar¬ 
bitrary feature. You could, of course, alter this function to display all 
files, or files selected according to another criterion (or allow the user to 
specify the criterion). 


LMJDELETEALL 

Purpose: 

This message is sent to a list box control window to delete all 
items in the list box. 

Parameters: 

MPARAM mpl 0. 

MPARAM mp2 0. 

Return Value: 

TRUE if the operation was successful, or FALSE if an error 
occurred. 


• Figure 8.31: 

The LM_DELETEALL Presentation Manager message 
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LM_IN SERTITEM 

Purpose: 

This message is sent to a list box control window to cause it 
to add an item to the list. 


Parameters: 

MPARAM mpl 

low-order word: 


One of the following flags, indicating 
where the item is to be inserted: 


Flag 

LIT_END 

LIT_SORTASCEND- 

ING 

LIT_SORTDESCEND- 

ING 


Position 
At end of list 
In ascending order 

In descending order 


high-order word: 

MPARAM mp2 


The far address of buffer containing 
the text for the item. 


Return Value: 

The index of the inserted item, or one of the following error 
codes if the function is unsuccessful: 


LIT MEMERROR 


LIT ERROR 


Meaning 

The list box does not have 
sufficient memory to allocate 
space for the item. 

All other errors. 


Figure 8.32: 

The LM_INSERTITEM Presentation Manager message 
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• CONCLUSION 

Listed at the end of this chapter is the complete set of files required 
to prepare the current version of the example program. The following 
files are provided: 

Figure File 

8.33 A MAKE file for preparing the example program 

8.34 The linker definition file 

8.35 The dialog resource script 

8.36 The general resource script 

8.37 The header file containing definitions for the Presenta¬ 
tion Manager resources 

8.38 The C source code file 

The linker definition file of Figure 8.34 is the same as those provided 
for previous versions of the example program, except that each of the 
dialog procedures is listed under the EXPORTS statement. Note that 
the dialog resource script of Figure 8.35 is generated directly by the 
Dialog Box Editor; this file is included by the general resource script 
file of Figure 8.36. The resource script of Figure 8.36 is processed by the 
resource compiler, and is the same as the script file described in Chap¬ 
ter 7 except for the statement that includes the dialog resource script. 
The header file of Figure 8.37 is included both in the resource script 
(Figure 8.36) and in the C source file (Figure 8.38). 

This chapter concludes the treatment of basic Presentation Manager 
features. The version of the example text editor program given here is 
the last complete listing of this application provided in the book. The 
remaining chapters discuss more advanced Presentation Manager fea¬ 
tures, and offer suggestions for incorporating these features into the 
current version of the example program. The example listings given in 
subsequent chapters consist of short programs and program fragments. 
You can, however, add these features to the example program listed in 
this chapter both to increase the usefulness of this application and as an 
exercise in Presentation Manager programming. 




# Figure 8.33 

# This MAKE file prepares the program of Figure 8.38. The following 

# are involved: 

# FIG8_3 3.MAK 

# FIG8_3 4.DEF 

# FIG8_35.DLG 

# FIG8_3 6.RC, FIG8_3 6.RES 

# FIG8_37.H 

# FIG8_38.C 

# 

FIG8__38 . OEsJ : FIG8_38.C FIG8_37.H 
Cl /W2 /c /Zp /G2ws FIG8_38.C 

FIG8_38.EXE : FIG8_35.DLG FIG8_36.RC FIG8_37.H 
rc /r FIG8_36.RC 

FIG8 38.EXE : FIG8_38.0BJ FIG8_34.DEF FIG8_36.RES 

link /NOD FIG8_38.OBJ, , NUL.LST, 0S2.LIB SLIBCE.LIB, FIG8_34.DEF 
rc FIG8 36.RES FIG8_38.EXE 


• Figure 833: 

A MAKE file for preparing the example program 



HEAPS I'ZE 1024 

STACKSIZE 8192 

EXPORTS WndProc 

OpenProc 
SaveasProc 
AboutProc 
FindProc 
GotoProc 


© Figure 834: 

The linker definition file for the example program 






/* 

Figure 8.35 

Dialog resource script for the program of Figure 8.38. 

V 

DLGTEMPLATE 257 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN 

DIALOG 257 , 69, 37, 180, 74, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "Save File As:", -1, 3, 50, 63, 8, WC_STATIC, 

SS_TEXT | DT_LEFT | DT_T0P | WS_GROUP | WS_VISIBLE 

CONTROL "", 257, 5, 31, 170, 13, WC_ENTRYFIELD, ES_LEFT | ES_AUTOSCROLL 
ES_MARGIN | WS_TABSTOP | WS_VISIBLE 

CONTROL "Current Directory:", 258, 3, 61, 174, 11, WC_STATIC, SS_TEXT | 
DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 

CONTROL "Esc=Cancel", 2, 99, 7, 56, 16, WC_BUTTON, BS_PUSHBUTTON | 
WS_VISIBLE 

CONTROL "Save", 1, 25, 8, 53, 14, WC_BUTTON, BS_PUSHBUTTON | BS_DEFAULT 
WS_TABSTOP | WS_VISIBLE 

END 

END 

DLGTEMPLATE 258 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN 

DIALOG "", 258, 71, 43, 182, 53, FS_NOBYTEALIGN | FS_DLGBORDER | 
WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "", 258, 37, 35, 141, 10, WC_ENTRYFIELD, ES_LEFT | 

ES_AUTOSCROLL | ES_MARGIN | WS_TABSTOP | WS_VISIBLE 

CONTROL "Esc=Cancel", 2, 105, 9, 60, 13, WC_BUTTON, BS_PUSHBUTTON | 
WSJVISIBLE 

CONTROL "Find", 1, 21, 9, 53, 13, WC_BUTTON, BS_PUSHBUTTON | BS_DEFAULT 
WS_TABSTOP | WS_VISIBLE 

CONTROL "Find:", -1, 6, 35, 23, 9, WC_STATIC, SS_TEXT | DT_LEFT | 

DT_TOP | WS_GROUP | WS_VISIBLE 

END 

END 


DLGTEMPLATE 259 LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "", 259, 90, 51, 147, 52, FS_NOBYTEALIGN | FS_DLGBORDER | 
WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "Go to Line Number:", -1, 3, 33, 86, 10, WC_STATIC, 

SS_TEXT | DT_LEFT | DT_TOP | WS_GROUP | WSJVISIBLE 
CONTROL "", 2 59, 96, -35, 45, 7, WC_ENTRYFIELD, ES_LEFT | ES_AUTOSCROLL 
ES_MARGIN | WS_TABSTOP | WS_VISIBLE 
CONTROL "Esc=Cancel", 2, 77, 11, 61, 14, WC_BUTTON, BS_PUSHBUTTON | 
WS_VISIBLE 

CONTROL "Go to Line", 1, 9, 12, 52, 12, WC_BUTTON, BS_PUSHBUTTON | 
BS_DEFAULT | WS_TABSTOP | WS_VISIBLE 

END 

END 


® Figure 8.35: 

The dialog resource script for the example program 
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ES AUTOSCROLL 


DLGTEMPLATE 260 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN , . 

DIALOG "", 260, 74, 17, 153, 123, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "Open File Name:", -1, 3, 108, 78, 10, WC_STATIC, 

SS TEXT I DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 

CONTROL ""7 260, 5, 93, 132, 11, WC_ENTRYFIELD, ES_LEFT | ES_AUTOSCROLL 
ES'MARGIN I WS_TABSTOP | WS_VISIBLE 

CONTROL ""7 261, 3, 67, 137, 8, WC_STATIC, SS_TEXT | DT_LEFT | 

DT TOP I WS GROUP | WS_VISIBLE 

CONTROL ""7 262, 5, 6, 82, 57, WC_LISTBOX, WS_TABSTOP | WS_VISIBLE 

CONTROL "Open", 1, 95, 41, 57, 13, WC_BUTTON, BS_PUSHBUTTON | BS_DEFAULT 
WS TABSTOP I WS VISIBLE 

CONTROL "Esc=Cancel", 2, 93, 12, 59, 16, WCJ3UTTON, BS_PUSHBUTTON | 

WS VISIBLE . 

CONTROL "Current Directory:", -1, 3, 79, 76, 9, WC_STATIC, SS_TEXT | 
DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE 


WS VISIBLE 


DLGTEMPLATE 256 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN , . 

DIALOG "", 256, 108, 32, 114, 85, FS_NOBYTEALIGN | FS_DLGBORDER | 

WS_CLIPSIBLINGS | WS_SAVEBITS 

BEGIN 

CONTROL "Presentation Manager", -1, 2, 67, 110, 9, WC_STATIC, 

SS_TEXT | DT_CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "Text Editor", -1, 2, 54, 109, 9, WC_STATIC, SS_TEXT | 

DT_CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "Version 1.0", -1, 3, 40, 109, 9, WC_STATIC, SS_TEXT | 

DT CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL "OK", 1, 39, 15, 34, 12, WC_BUTTON, BS_PUSHBUTTON | BS_DEFAULT 

WS GROUP I WS TABSTOP I WS VISIBLE 


67, 110, 9, WC_STATIC, 

WS_GROUP | WSJVISIBLE 


® Figure 835: 

The dialog resource script for the example program (continued) 
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/* 

Figure 8.37 

Header file to be included in the resource file of Figure 8.36 and the 
C source file of Figure 8.38 

V 

#define ID_FRAME_RESOURCE 1 


#define ID FILE 

10 

#define ID NEW 

11 

#define ID OPEN 

12 

#define ID SAVE 

13 

#define ID SAVEAS 

14 

#define ID "PRINT 

15 

#define ID EXIT 

16 

#define ID_ABOUT 

17 

#define ID EDIT 

20 

#define: ID CUT 

21 

#define ID COPY 

22 

#define ID~PASTE 

23 

#define ID SEARCH 

30 

#define ID FIND 

31 

#define ID~FINDNEXT 

32 

#define ID_GOTOLINE 

33 

#define ID OPTIONS 

40 

#define ID_INSERT 

41 

#define ID_HELP 

50 

#define ID ABOUTDLG 

256 

#define ID SAVEASDLG 

257 

#define ID SAVEASEDIT 

257 

#define ID'_SAVEASCD 

258 

#define ID FINDDLG 

258 

#define ID^FINDEDIT 

258 

#define ID GOTODLG 

259 

#define ID~GOTOEDIT 

259 

#define ID OPENDLG 

260 

#define ID' OPENEDIT 

260 

#def ine ID' OPENCD 

261 

#define ID OPENLIST 

262 


@ Figure 837: 

The header containing definitions for the example program resources 
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Figure 8.38 

Version 5 of the Presentation Manager text editor example program. 

This version adds the following features: 

o A Presentation Manager menu for selecting commands 
o Accelerator keys for rapidly accessing frequently used menu items 
o Dialog boxes for interacting with the user for certain menu items 
o An "About" dialog box 
o Commands for managing file I/O: 
o opening a new file 
o reading an existing file 

o saving the file being edited, under its original name 
o saving the file under a new name 
o A command for searching for a string within the file 
o A command for moving the cursor to a specific line within the file 
o A menu command for toggling between overwrite and insert modes 


#define INCL_GPI 
#define INCL_WIN 
#include <0S2.H> 
#include <STDI0.H> 

#include <PR0CESS.H> 
#include <10.H> 
#include <STRING.H> 
#include <STDLIB.H> 


/* Include all Gpi... function declarations. 
/* Include all Win... function declarations. 

/* C library header files: 


#include "FIG8_37.H" /* Definitions shared with resource script. */ 
/*** window procedure declaration. *******************************************/ 
MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 

/*** Declarations / definitions for file- and buffer-management module. ******/ 


#define LINEBUFSIZ 2 
#define ERROPEN ] 
#define ERRTOOBIG 2 
#define ERRMAXLINES 2 
#define ERRALLOC 4 

void Buflnit (void); 


/* Size of buffer for holding lines. 

/* Error: opening file. 

/* Error: file too large. 

/* Error: maximum file lines exceeded. 
/* Error: heap allocation. 


void Buflnit (void); /* Initializes buffer-management module. 

/* Deletes character from buffer: 
int DeleteChar (SHORT Line, SHORT Column)? 

void DeleteLine (SHORT Line); /* Deletes the current line. 


char *ErrorMessage (int ErrorNumber); /* Returns error message string. 

PCH GetLineAddr (int Line); /* Gets address of line in buffer. 

SHORT GetLineLength (int Line); /* Gets length of line in buffer, 

void GetTempBuf (int Line); /* Obtains a temporary line buffer. 

/* Inserts character into buffer: 

int InsertChar (SHORT Line,USHORT Character,SHORT Column, int Overwrite); 


• Figure 8.38: 

The C source code file for the example program 
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/* Inserts new line into buffer 
void InsertLine (SHORT Line, SHORT Column); 


int JoinLine (SHORT Line); 

void NewFile (void); 

int ReadFile (char *FileName); 

void ReleaseFile (void); 

void ReleaseTempBuf (int Line); 

int SaveFile (char *FileName); 


/* Joins line to previous line. 

/* Initializes buffer for a new file. 
/* Reads file into editor buffer. 

/* Destroys current heap. 

/* Releases temporary line buffer. 

/* Save buffer under specified name. 


int SearchBuf (char *FindString, PSHORT Line, PSHORT Col); /* Find string. 


int LastLine = -1; 
HHEAP HHeap = NULL; 


/* Number of last line in buffer. 
/* PM heap handle. 


/*** Utility function declarations. ******************************************/ 

void ErrorQuit (char ^Message); /* Print error message, end program. */ 

char *Extension (char *FileName); /* Returns pointer to file extension. */ 

void GetPath (char *Path, unsigned PathLength); /* Obtains directory path. */ 
void InitWindow (void); /* Sets parameters for a new file. */ 

void Qualify (char *Ungual, char *Qual);/* Fully qualifies a file path name. */ 
void Quit (int ErrorCode); /* Terminate_the PM program. < */ 

void ShowFileName (void); /* Updates title bar with new file name. */ 

char *Unqualify (char *Qual); /* Unqualifies a file path name. */ 

/*** Global definitions / variables. *****************************************/ 


#define PATHLENGTH 128 

HWND B: Frame; 

HWND HMenu; 

HAB HAncBlk; 

HMQ HMesQue; 

char Message [64]; 

char FileName [PATHLENGTH]; 

char Title [25] = 

unsigned char Modified = 0; 

HWND KClient; 


/* Maximum length of file path. 

/* Handle to main frame window. 

/* Handle to menu window. 

/* Handle to anchor block. 

/* Message queue handle. 

/* Buffer for displaying error messages. 
/* Name of current file. 

/* Text for title bar. 

/* Flag indicating whether file modified. 
/* Handle to main client window. 


void main (int argc, char *argv[]) 
{ 

int ReadError = 0; 

QiMSG QueMess; 

ULONG CtlData = 

FCFJHORZSCROLL 

FCF_MENU 

FCF_MINMAX 

FCF_SHELLPOSITION 

FCF_SIZEBORDER 

FCF_SYSMENU 

FCF_TASKLIST 

FCF_TITLEBAR 

FCF VERTSCROLL; 


BufInit (); 


/* Error occurred reading file. 

/* Message structure. 

/* Control windows to include. 

/* Horizontal scroll bar. 

/* Menu. 

/* Minimize/maximize box. 

/* Make window visible on screen. 

/* Wide sizing border. 

/* System menu. 

/* Display program name in Task Manager. 
/* Title bar. 

/* Vertical scroll bar. 

/* Initialize buffer module. 


® Figure 838: 

The C scurce code file for the example program (continued) 
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/*** 

If no file name given, set 1 

FileName’ to NULL and open new file. ********/ 


if (argc < 2) 

f 




\ 

FileName [0] = 1 \0'; 




NewFile (); 



/*** 

If file name given, save fully qualified name and read file. ************/ 


else 




Qualify (argv [1],FileName); 



ReadError = ReadFile (FileName); 

} 



HAncBlk = Winlnitialize (0); 

/* Initialize PM system for process. 

*/ 


HMesQue = WinCreateMsgQueue 

(HAncBlk,0); /* Create a message queue. 

*/ 


WinRegisterClass 

/* Register procedure for main window. 

V 


(HAncBlk, 

/* Anchor block handle. 

*/ 


"MAIN”, 

/* Window class name. 

*/ 


WndProc, 

/* Window procedure associated w/ class. 

V 


0L, 

/* Class style. 

*/ 


0) ? 

/* Extra storage bytes. 

*/ 


HFrame = WinCreateStdWindow 

/* Create parent window. 

*/ 


(HWND DESKTOP, 

/* Parent window handle. 

*/ 


FS ACCELTABLE | 

/* Install accelerator table. 

*/ 


WS VISIBLE, 

/* Frame window style. 

*/ 


&CtlData, 

/* Address of control data. 

*/ 


"MAIN”, 

/* Client window class name. 

*/ 


Title, 

/* Text for title bar. 

*/ 


0L, 

/* Client window style. 

V 


0, 

/* Resource module handle. 

*/ 


ID FRAME RESOURCE, 

/* Resource identification. 

*/ 


&HClient); 

/* Address to receive client window hand. 

V 


if (HFrame == NULL) 




ErrorQuit ("WinCreateStdWindow"); 



ShowFileName (); 

/* Display file name in window title. 

*/ 


HMenu = WinWindowFromID 

/* Get handle of menu window. 

*/ 


(HFrame, 

/* Handle of parent frame window. 

*/ 


FID_MENU); 

/* ID of menu child window. 

*/ 


if (ReadError) 

/* Quit if read error. 

*/ 


ErrorQuit (ErrorMessage 

(ReadError)) ; 



WinSetFocus 

/* Give focus to client window. 

*/ 


(HWND DESKTOP, 

/* Handle for desktop window. 

V 


HClient); 

/* Client window handle. 

*/ 


while (WinGetMsg 

/* Get messages until WM QUIT. 

V 


(HAncBlk, 

/* Anchor block handle. 

V 


• Figure 8.38: 
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&QueMess, 

0 , 

0 , 

0 )) 


/* Address of message structure. 
/* Window filter. 

/* First message identifier. 

/* Last message identifier. 


WinDispatchMsg (HAncBlk,&QueMess) ; /* Dispatch messages. 

Quit (0)? /* Normal termination. 

} /* end main */ 


, , I • *-at*************************************/ 

Window procedure and subroutines. *************** 7 


MRESULT EXPENTRY Character 
MRESULT EXPENTRY Command 
MRESULT EXPENTRY Create 
MRESULT EXPENTRY Help 
MRESULT EXPENTRY HScroll 
MRESULT EXPENTRY InitMenu 
MRESULT EXPENTRY Paint 
MRESULT EXPENTRY SetFocus 
MRESULT EXPENTRY Size 
MRESULT EXPENTRY VirtKey 
MRESULT EXPENTRY VScroll 


(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 
(HWND hwnd, 


USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2)7 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT msg, MPARAM mpl, MPARAM mp2); 
USHORT rnsg, MPARAM mpl, MPARAM mp2)7 
USHORT msg, MPARAM mpl, MPARAM mp2); 


/*** Dialog procedures. 




MRESULT EXPENTRY OpenProc (HWND hwnd, 
MRESULT EXPENTRY SaveasProc(HWND hwnd, 
MRESULT EXPENTRY AboutProc (HWND hwnd, 
MRESULT EXPENTRY FindProc (HWND hwnd, 
MRESULT EXPENTRY GotoProc (HWND hwnd, 


USHORT msg, MPARAM mpl, MPARAM mp2 )7 
USHORT msg, MPARAM mpl, MPARAM mp2)7 
USHORT msg, MPARAM mpl, MPARAM mp2)7 
USHORT msg, MPARAM mpl, MPARAM mp2)7 
USHORT msg, MPARAM mpl, MPARAM mp2)7 


void NotYet (char Message); /* Displays 'not implemented' message. 


*/ 


static SHORT xChar; 
static SHORT yCharTot; 
static SHORT yCharDesc; 
static SHORT xWin? 
static SHORT yWin; 
static HWND HVScroll? 
static HWND HHScroll; 
static int FirstCol,* 
static int FirstColMax; 
static SHORT TopLine = 0; 
static SHORT TopLineMax; 
static FATTRS FontAttributes? 


/* Character width. 

/* Total height of characters. 

/* Height of character descenders. 

/* Horizontal size of window. 

/* Vertical size of window. 

/* Handle to vertical scroll bar window. 

/* Handle to horizontal scroll bar window. 

/* Character to be in first column position. 
/* Maximum value of 'FirstCol'. 

/* Number of top line in window. 

/* Maximum value of 'TopLine'. 

/* Stores font attributes from GpiQueryFonts. 


*/ 

V 

V 
*/ 
*/ 

V 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


/*** cursor-management variables, 
static SHORT CursorLine = 0; 
static SHORT Cursored = 0; 
static SHORT LastCursorLine = 0; 


********************************************/ 
/* Current line location of cursor. */ 

/* Current column location of cursor. */ 

/* Last line position of cursor. */ 


/*** Flag for insert mode. 


************************** 
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static int Insert = 1; 
static int BlockMarked = 0; 
static int ClipData = 0; 
static char Findstring [33] 


/* if 0/ overwrite mode, if 1, insert mode. 
/* Flag for marked block. 

/* Flag indicating clipboard has data. 

= {*\0 * }; /* Holds the search string. 


#define ID_COURIER 99L 

/* 

Local font ID. 


MRESULT EXPENTRY WndProc 

(HWND hwnd, 

/* 

Window handle. 


USHORT msg, 

/* 

The message. 


MPARAM mpl, 

/* 

Message-specific 

information. 

MPARAM mp2) 

( 

/* 

Message-specific 

information. 

switch (msg) 

/ 

case WM CHAR: 

/* 

Message sent when 

keyboard key 

/* Key was 

released. 

if (CHARMSG 

(&msg) 

— > fs & KC_KEYUP) 


return 

FALSE; 




V 

V 

V 

V 


*/ 

V 

V 

*/ 


V 

V 


/* Valid character key. */ 

else if (CHARMSG (&msg)->fs & KC_CHAR) 

return Character (hwnd, msg, mpl, mp2); 

/* Valid virtual key code. */ 

else if (CHARMSG (&msg)->fs & KC_VIRTUALKEY) 
return VirtKey (hwnd, msg, mpl, mp2); 

/* Invalid key: neither virtual nor character. */ 

else 

return FALSE; 

/*** Process WM__COMMAND message sent when user selects a menu item. *****/ 
case WM_COMMAND: 

return Command (hwnd, msg, mpl, mp2); 

case WM_CREATE: /* Message sent when window is first created. */ 

return Create (hwnd, msg, mpl, mp2); 

/*** Process WM_HELP message sent when user selects help or presses FI. */ 
case WM_HELP: 

return Help (hwnd, msg, mpl, mp2); 

case WM_HSCROLL: /* Message sent on horizontal scroll activity. */ 

return HScroll (hwnd, msg, mpl, mp2); 


/*** Process WM_INITMENU message sent when menu item is first selected. */ 

u (hwnd, msg, mpl, mp2); 

/* Message sent when window data is invalid. */ 


case WM_INITMENU: 

return InitMenu (hwnd, msg, mpl, mp2); 
case WM PAINT: 


• Figure 838: 
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return Paint (hwnd, msg, mpl, mp2); 

case WM SETFOCUS: /* Message sent when client focus changes. */ 

return SetFocus (hwnd, msg, mpl, mp2); 

case WM SIZE: /* Message sent whenever window changes size. */ 

return Size (hwnd, msg, mpl, mp2); 

case WM VSCROLL: /* Message sent on vertical scroll activity. */ 

return VScroll (hwnd, msg, mpl, mp2); 

default: /* Perform default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} /* end switch */ 

} /* end WndProc */ 


/*** Subroutines called by window procedure. 




MRESULT EXPENTRY Character (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

register int Col; /* Used for loop to generate tab characters. 

RECTL Rect; /* Holds coordinates of rectangle. 


*/ 

V 


/*** Set global ’Modified’ 
Modified = 1; 




if (LastCursorLine != CursorLine) /* Adjust buffer for new cursor */ 

v ( /* line. */ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

if (CHARMSG(&msg)->chr == '\b*) /* Process a backspace key. */ 

i£ (CursorCol —— 0) Cursor at first column. / 

if (CursorLine == 0) /* Cursor in first line. */ 

return TRUE; 


WinSendMsg 
(hwnd, 
WM_CHAR, 
MPFROM2SHORT 
MPFR0M2SHORT 
WinSendMsg 
(hwnd, 
WM_CHAR, 
MPFR0M2SHORT 
MPFR0M2SHORT 


/* Send up-arrow message to self. 
/* Client window handle. 

/* Character received message. 
(KC_VIRTUALKEY, 1), /* A virtual key. 

(0, VK_UP)); /* Up-arrow code. 

— /* Send End message to self. 

/* Client window handle. 

/* Character received message. 

(KC_VIRTUALKEY, 1), /* A virtual key. 

(0, VK_END)); /* End code. 


*/ 

*/ 

*/ 

*/ 

*/ 

V 
*/ 
*/ 

V 

V 


if (!Insert) 


/* in overwrite mode, task finished. */ 
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return TRUE; 


if (!JoinLine (CursorLine +1)) /* Join lines. */ 

{ 

WinAlarm (HWND_DESKTOP, WA_ERROR); 
return TRUE; 

} 


LastCursorLine = CursorLine; 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 


WinSendMsg /* Send message to vertical scroll bar. */ 

(HVScroll, /* Recipient handle. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable only scroll possible. */ 

(HVScroll, /* Recipient handle. */ 

TopLineMax ? 1 : 0); /* Enable only if max. != 0. */ 


Rect.xLeft - 0; /* Calculate invalid rectangle. */ 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 
Rect.yBottom =0; 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* Don't include descendants w/ WS_CLIPCHILDREN*/ 

WinUpdateWindow (hwnd); /* Force window update. */ 

return TRUE; 

} /* end cursor at column 0 */ 


WinSendMsg /* Send left-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KCJVIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VK_LEFT)) ; /* Left-arrow code. */ 

if (Insert) /* If in insert mode, delete character. */ 

WinSendMsg /* Send Del message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character received message. */ 

MPFROM2SHORT (KCJVIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VK_DELETE)); /* Del key code. */ 

e l se /* If in overwrite mode, overwrite current character */ 

{ /* with a space. */ 

WinSendMsg /* Send space character message to self. */ 

(hwnd, /* Client window handle. */ 

WM_CHAR, /* Character message. */ 
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MPFR0M2SHORT (KC_CHAR, 1), /* Character key. */ 

MPFROM2SHORT (' ',0)); /* Space character. */ 

WinSendMsg /* Send left-arrow message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character received message. */ 

MPFROM2SHORT (KC_VIRTUALKEY, 1), /* Virtual key. */ 

MPFROM2SHORT (0, VK_LEFT)) ; /* Left-arrow code. */ 


} /* end overwrite mode */ 
return TRUE; 

) /* end '\b' */ 

if (CHARMSG(&msg)->chr == '\t') /* Process a Tab key. 

{ 

Col = 5 - Cursored % 5 ; 


while (Col—) 

WinSendMsg /* Send space character message to self. */ 

(hwnd, /* Client window handle. */ 

WM CHAR, /* Character message. */ 

MPFROM2SHORT (KC_CHAR, 1), /* Character key. */ 

MPFROM2SHORT (' ’,0)); /* Space character. */ 

return TRUE; 

} /* end '\t' */ 

if (CHARMSG(&msg)->chr == '\r') /* Process an Enter key. */ 

if (Insert) /* Insert mode is active. */ 


InsertLine (CursorLine, CursorCol); 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 


WinSendMsg /* Adjust scroll bar range. */ 

(HVScroll, /* Recipient handle (vertical scroll bar).*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable only if scroll possible. */ 

(HVScroll, /* Recipient handle (vertical scroll bar).*/ 

TopLineMax ? 1 : 0); /* Enable only if max. !— 0. */ 


Rect.xLeft = 0; /* Calculate invalid rectangle. */ 

Rect.xRight = xWin; 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot; 

Rect.yBottom = 0; 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Client window handle. _ _ */ 

&Rect, /* Dimensions of rectangle to invalidate. */ 

FALSE); /* Don't include descendants w/ WS_CLIPCHILDREN*/ 
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WinUpdateWindow (hwnd); 

} /* end insert mode */ 

WinSendMsg 
(hwnd, 

WM_CHAR, /* 

MPFROM2SHORT (KC_VIRTUALKEY, 
MPFROM2SHORT (0, VK_DOWN)); 

if (Insert) 

LastCursorLine = CursorLine; 

WinSendMsg /* 

(hwnd, /* 

WM_CHAR, /* 

MPFROM2SHORT (KC_VIRTUALKEY, 
MPFROM2SHORT (0, VK_HOME))? 

return TRUE; 


/* Force window update. 


Move cursor down. 

Client window handle. 
Character received message. 
1) , 


Send Home key message to self 
Client window handle. 
Character received message. 
1), /* Virtual key. 

/* Home key code. 


/* 

/* 


*/ 


V 

V 

V 


V 

*/ 

V 

*/ 

*/ 


) /* end ! \r 1 */ 

if (IlnsertChar /* Insert normal key into file buffer. 

(CursorLine, 

CHARMSG(&msg)->chr, 

CursorCol, 

Insert)) 

( 

WinAlarm (HWND_DESKTOP, WA_ERR0R); 
return TRUE; 

} 


/* Calculate invalid rectangle. 

Rect.xLeft = (CursorCol - FirstCol) * xChar; X 

Rect.xRight = min.((GetLineLength (CursorLine) - FirstCol) * xChar xWin); 
Rect.yBottom m yWin - (CursorLine - TopLine + 1) * yCharTot; 

Rect.yTop = Rect.yBottom + yCharTot; 


WinlnvalidateRect 
(hwnd, 

&Rect, 

FALSE); 


/* Invalidate section to be modified. */ 
/* Handle of client window. */ 
/* Rectangle to be added to invalid region. */ 
/* Don't include descendants w/ WS_CLIPCHILDREN*/ 


WinUpdateWindow (hwnd); /* Force updating of client window. 


WinSendMsg /* 

(hwnd, /* 

WM_CHAR, /* 

MPFROM2 SHORT (KC_VIRTUALKEY,1) , 

MPFROM2SHORT (0, VK_RIGHT)); 


Send right-key message to self. */ 

Client window handle. */ 

Character message. */ 

/* mpl. */ 

/* mp2. */ 


return TRUE; 


} /* end Character */ 
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MRESULT EXPENTRY Command (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

USHORT Result; /* WinDlgBox return code. */ 

USHORT Update = FALSE; /* Flag indicating whether window update needed*/ 

USHORT Reply; /* Response from message box. */ 

/*** Branch according to code for the menu item selected. ********************/ 


switch (COMMANDMSG (&msg)->cmd) 

case ID NEW: /* 'New' file menu item. */ 

if (Modified) /* File is modified. */ 

/* Warn user and elicit response on saving file. */ 

Reply = WinMessageBox 
(HWND_DESKTOP, 
hwnd, 

"File Unsaved; Save?”, 

"PM Text Editor", 

0 , 

MB_YESN0 | 

MB_ICONQUESTION); 

/* If reply is Yes, send a 'Save' message to client. */ 

if (Reply == MBID_YES) 

/* Repeat message until file successfully saved. */ 
while (Modified) 

WinSendMsg 

(hwnd, 

WM_COMMAND, 

MPFR0M2 SHORT (ID_SAVE, 0) , 

0L) ; 


} /* end if Modified */ 


ReleaseFile (); 
NewFile (); 

FileName [0] = '\0'; 
ShowFileName ()? 
Modified = 0; 
InitWindow (); 


/* Free current heap. */ 
/* Initialize a new file. */ 
/* New file is untitled. */ 
/* Display "Untitled" in title bar. */ 
/* Reset modified flag. */ 


/* Set initial window/cursor values. */ 


return FALSE; 


case ID_0PEN: /* 'Open' file menu item. */ 

/* Process message using a dialog box. */ 

WinDlgBox 

(HWND_DESKTOP, /* Handle of parent window: desktop. */ 

hwnd, /* Handle of owner: client. */ 

OpenProc, /* Dialog procedure. */ 
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NULL, 

ID OPENDLG, 
NULL); 

/* 

/* 

/* 

Resource module: the .EXE 
Name ID of dialog window: 
Pointer to procedure data: 

file. 
Open. 
n/a. 

*/ 

*/ 

V 

return FALSE; 







case ID 

SAVE: 

/* 

'Save' item of 'File' 

submenu. 

*/ 

/* 

/* 

if 

If 'FileName' is 
current name. 
(FileName [0]) 

non-null 

, save the 

file under 

the 


V 

*/ 


{ 

if (SaveFile (FileName) == FALSE) 


/* Save failed; therefore display a message. */ 

WinMessageBox 

(HWND_DESKTOP, 

HFrame, 

"Error — Cannot Save File", 

"PM Text Editor", 

0 , 

MB_0K | 

MB_ICONASTERISK); 


else 

/* Save successful; therefore reset 'Modified 1 flag*/ 
Modified - 0; 


return FALSE; 

) 

/* IF 'FileName' IS NULL, DROP THROUGH TO ID_SAVEAS CASE. */ 


case ID SAVEAS: 


/* 'Save As' item of 'File' submenu. */ 


/* Process message using a dialog box. 
WinDlgBox 


V 


(HWND_DESKTOP, 

/* 

hwnd, 

/* 

SaveasProc, 

/* 

NULL, 

/* 

ID SAVEASDLG, 

/* 

NULL) ; 

/* 

return FALSE; 

ID_PRINT: 

/* 


/* Handle of parent window; desktop. */ 
Handle of owner: client. */ 

Dialog procedure. */ 

Resource module: the .EXE file. */ 
Name ID of dialog window: Saveas.*/ 
Pointer to procedure data: n/a. */ 


'Print' item of 'File' submenu. 


/* Command not implemented. 
NotYet ("Print File Command"); 
return FALSE; 


case ID_EXIT: /* 'Exit' item of 'File' submenu. */ 

/* Exit program. */ 

Quit (0); 
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return FALSE; 
case ID ABOUT; 


/* Display 
WinDlgBox 

(HWND_DESKTOP, 
hwnd, 

AboutProc, 

NULL, 

ID_ABOUTDLG, 
NULL); 

return FALSE; 

case ID_CUT; 
case ID_COPY: 
case ID PASTE; 


/* 'About* item 'File' submenu. 
About' box using a dialog box. 


/* 

/* 

/* 

/* 

/* 

/* 


Handle of parent window; desktop. 
Handle of owner; client. 

Dialog procedure. 

Resource module; the .EXE file. 
Name ID of dialog window; About. 
Pointer to procedure data; n/a. 


*/ 

*/ 

V 

V 

V 

*/ 

V 

*/ 


/* 'Cut' item of 'Edit' submenu. 

/* 'Copy' item of 'Edit' submenu. 
/* 'Paste' item of 'Edit' submenu. 


/* These commands are not implemented. 
NotYet ("Clipboard Commands"); 
return FALSE; 


case ID FIND; 


/* Process command through a dialog box. 
Result = WinDlgBox 


(HWND_DESKTOP, 
hwnd, 

FindProc, 

NULL, 

ID_FINDDLG, 
NULL) ; 


if (Result) 

{ 


/* Redisplay window for new position in file. 
WinlnvalidateRect /* Invalidate window. 

(hwnd, /* Handle of client window. 

NULL, /* Invalidate ENTIRE window. 

FALSE); 

WinUpdateWindow (hwnd); /* Force updating of window. 

WinSendMsg /* Set horizontal scroll bar position. 

(HHScroll, 

SBM_SETPOS, 

MPFR0M2 SHORT (FirstCol,0) , 

0 ) ; 


WinSendMsg /* 

(HVScroll, 
SBM_SETPOS, 
MPFROM2SHORT 
0 ) ; 


Set vertical scroll bar position. 


(TopLine, 0) 
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/* 'Find' item of 'Search' submenu. */ 


/* Handle of parent window: desktop. 
/* Handle of owner: client. 

/* Dialog procedure. 

/* Resource module: the .EXE file. 
/* Name ID of dialog window: Find. 

/* Pointer to procedure data: n/a. 

/* Window needs repainting. 


*/ 

*/ 

V 

*/ 

V 

V 

*/ 

*/ 

V 

V 

V 

V 
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return FALSE; 
case ID FINDNEXT: 


/* 'Find Next* item of 'Search' submenu. */ 

/* Search for string — update cursor position if found. */ 

if (SearchBuf (Findstring, SCursorLine, SCursorCol) == FALSE) 

{ 

/* String not found. */ 

WinMessageBox 

(HWND_DESKTOP, 

HFrame, 

"String not found", 

"PM Text Editor", 

0 , 

MB_0K | 

MB_ICONASTERISK); 

return FALSE; 

} 

/* Adjust 'TopLine' for position of found string. */ 

if (CursorLine < TopLine || 

CursorLine >= TopLine + yWin/yCharTot) 

TopLine = max (0,CursorLine - (yWin/yCharTot)/2); 

TopLine = min (TopLine,TopLineMax); 

Update = TRUE; 

} 

/* Adjust 'FirstCol' for position of found string. */ 

if (Cursored < FirstCol | | 

CursorCol >= FirstCol + xWin / xChar) 

FirstCol = max (0,CursorCol - (xWin/xChar)/2); 

FirstCol = min (FirstCol,FirstColMax); 

Update = TRUE; 

} 

/* Update window if necessary to display a new file position. */ 
if (Update) 7 


/* Invalidate whole window. 


{ 

WinlnvalidateRect 
(hwnd, 

NULL, 

FALSE); 

WinUpdateWindow (hwnd); /* Force immediate updating. 

WinSendMsg /* Adjust horizontal scroll bar. 

(HHScroll, 

SBM_SETPOS, 

MPFROM2 SHORT (FirstCol,0) , 

o) ; 


*/ 

V 
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WinSendMsg /* Adjust ver' 

(HVScroll, 

SBM_SETPOS, 

MPFR0M2SHORT (TopLine, 0) , 

0 ) ; 

} 

/* Reposition the cursor. 
WinCreateCursor 
(hwnd, 

(Cursored - FirstCol) * xChar, 
yWin - (CursorLine - TopLine + 1) 
0 , 

0 , 

CURS0R_SETP0S, 

NULL) ; 


/* Adjust vertical scroll bar. 


yCharTot, 


return FALSE; 


case ID GOTOLINE: 


/* 'Go to Line' item of 'Search' submenu. */ 


/* Process command through a dialog box. **********************/ 
Result = WinDlgBox /* Display dialog box. */ 

(HWND DESKTOP, /* Handle of parent window: desktop. */ 


hwnd, 
GotoProc, 
NULL, 

ID_G0T0DLG, 
NULL) ; 


/* Handle of owner: client. 

/* Dialog procedure. 

/* Resource module: the .EXE file. 
/* Name ID of dialog window: Goto. 
/* Pointer to procedure data: n/a. 


/* if command executed, force updating of entire window, 
if (Result) 

WinlnvalidateRect /* Invalidate entire window, 

(hwnd, 

NULL, 

FALSE); 

WinUpdateWindow (hwnd); /* Force window update. 

WinSendMsg /* Set horizontal scroll bar position. 

(HHScroll, 

SBM_SETPOS, 

MPFR0M2SHORT (FirstCol,0), 

o) ; 

WinSendMsg /* Set vertical scroll bar position. 

(HVScroll, 

SBM_SETPOS, 

MPFROM2SHORT (TopLine, 0), 

0 ) ; 


return FALSE; 
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case ID_INSERT: 

Insert A = 1; 
return FALSE; 

default: 

return FALSE; 

} /* end switch */ 

} /* end Command */ 


/* 'Overwrite Mode'/'Insert Mode' item of */ 
/* 'Options' submenu. */ 
/* Toggle 'Insert' global flag. */ 


MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

HPS HPresSpace; /* Presentation space handle. 

FONTMETRICS Metrics; /* Structure to hold font dimensions. 

LONG NumberStructs =1; /* Number of structures from GpiQueryFonts 


GpiLoadFonts /* Load Courier font. 

(HAncBlk, /* Anchor block handle. 

"\\0S2\\DLL\\C0URIER.F0N"); /* Full path name of font file. 

HPresSpace = WinGetPS (hwnd); 


GpiQueryFonts 

(HPresSpace, 
QF_PRIVATE, 
"Courier", 
&NumberStructs, 


/* Obtain information on Courier font. 


/* Handle to presentation space. 


Enumerate private fonts. 

Font face name. 

Number of FONTMETRICS structures returned. 
(long)sizeof (FONTMETRICS),/* Length of structure for EACH font. 
SMetrics); /* Address of FONTMETRICS structure(s). 


*/ 

V 

*/ 

V 
*/ 
*/ 
*/ 


xChar 

yCharTot 

yCharDesc 


(SHORT)Metrics.lAveCharWidth; 
(SHORT)Metrics.lMaxBaselineExt; 
(SHORT)Metrics.IMaxDescender; 


FontAttributes.usRecordLength = sizeof (FontAttributes); 
FontAttributes.fsSelection = Metrics.fsSelection? 
FontAttributes.IMatch = Metrics.IMatch; 
strcpy (FontAttributes.szFacename,Metrics.szFacename); 
FontAttributes.idRegistry = Metrics.idRegistry? 
FontAttributes.usCodePage = Metrics.usCodePage; 
FontAttributes.lMaxBaselineExt = Metrics.lMaxBaselineExt; 
FontAttributes.lAveCharWidth = Metrics.lAveCharWidth; 
FontAttributes.fsType = FATTR_TYPE_FIXED; 

FontAttributes.fsFontUse = 0 ; 


WinReleasePS (HPresSpace); 


HHScroll = WinWindowFromID 

(WinQueryWindow (hwnd, QW_PARENT,FALSE), /* Handle to parent */ 

/* window (frame). */ 

FiD_H 0 RZSCROLL); /* Identifier for vertical scroll bar. */ 
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HVScroll = WinWindowFromID 

(WinQueryWindow (hwnd. 

QW PARENT,FALSE), /* Handle to parent 

*/ 

/* window (frame). 

*/ 

FID_VERTSCROLL); 

return FALSE; 

/* Identifier for vertical scroll bar. 

*/ 

} /* end Create */ 

MRESULT EXPENTRY Help (HWND hwnd, 

( 

NotYet ("Help Window"); 
return FALSE; 

USHORT msg, MPARAM mpl, MPARAM mp2) 


} /* end Help */ 

MRESULT EXPENTRY HScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


SHORT Delta; 

/* Amount to scroll. 

*/ 

switch (SH0RT2 FROMMP (mp2)) 

/* Branch according to code for the 

*/ 

{ 

case SB LINELEFT; 

Delta = -1; 
break; 

case SB LINERIGHT: 
Delta = 1; 
break; 

case SB_PAGELEFT: 

Delta = -6; 
break; 

case SB_PAGERIGHT; 
Delta = 6; 
break; 

/* scrolling event. 

*/ 

case SB SLIDERPOSITION 



Delta = SHORT1FROMMP (mp2) - FirstCol; 
break; 
default: 

Delta = 0; 
break; 


) 

Delta = max (-FirstCol, min 

(Delta,FirstColMax - FirstCol)); 


if (Delta) 

{ 

FirstCol += Delta; 
CursorCol += Delta; 

/* Generate scrolling, if necessary. 

*/ 

WinShowCursor 

/* Hide cursor. 

*/ 

(hwnd. 

/* Client window handle. 

*/ 

FALSE); 

/* Hide it! 

*/ 

WinScrollWindow 

/* Scroll window horizontally. 

*/ 
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(hwnd, 

/* 

Handle of client window. 

'*/ 

-Delta * xChar, 

/* 

Horizontal scroll amount. 

*/ 

0 , 

/* 

Vertical scroll amount. 

*/ 

0 , 

/* 

Must be 0. 

*/ 

0 , 

/* 

Must be 0. 

*/ 

o , 

/* 

Must be 0. 

*/ 

o , 

/* 

Must be 0. 

*/ 

SW_INVALIDATERGN); 

/* 

Invalidate "exposed" region. 

*/ 

WinUpdateWindow 

/* 

Force updating of client window. 

*/ 

(hwnd); 

/* 

Handle of client window. 

V 

WinSendMsg 

/* 

Adjust horizontal slider position 

*/ 

(HHScroll, 

/* 

Handle to horizontal scroll bar. 

V 

SBM SETPOS, 

/* 

Set position of slider. 

V 

MPFROM2 SHORT (FirstCol 

0 ) , 

/* Current position. 

*/ 

0 ) ; 


/* Second parameter: n/a. 

*/ 

WinCreateCursor 

/* 

Set position of cursor. 

*/ 

(hwnd, 

/* 

Client window handle. 

V 

(Cursored - FirstCol) 

* xChar, /* x position of cursor. 

V 

| yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. 

V 

0 , 

/* 

x size of cursor: n/a. 

*/ 

0 , 

/* 

y size of cursor: n/a. 

V 

CURSOR SETPOS, 

/* 

Option to set position only. 

V 

NULL) ; 

/* 

Clipping rectangle: n/a 

V 

WinShowCursor 

/* 

Show cursor. 

*/ 

(hwnd, 

/* 

Client window handle. 

*/ 

TRUE); 

/* 

Show it! 

V 

} /* end if (Delta) */ 




return FALSE; 




} /* end HScroll */ 




MRESULT EXPENTRY InitMenu (HWND hwnd, 

{ 

USHORT msg, MPARAM mpl, MPARAM mp2) 


/*** Branch on the code for the specific submenu that is being displayed. ****/ 

switch (SHORT1FROMMP (mpl)) 




( 

case ID EDIT: 

/* 

'Edit' submenu. 

V 

WinSendMsg 

/* 

Set attribute of ’Cut' menu item. 

*/ 

(HMenu, 

/* 

Handle of menu window. 

V 

MM SETITEMATTR, 
MPFROM2SHORT 

/* 

Set attribute of menu item. 

V 

(ID CUT, 

/* 

'Cut' menu item. 

*/ 

TRUE), 

/* 

Include submenus. 

V 

MPFROM2SHORT 




(MIA_DISABLED, /* 

Disabled attribute. 

V 
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/* Disable only if block not marked. 

*/ 

BlockMarked ? 

0 : MIA_DISABLED)); 


WinSendMsg 

/* Set attribute of 'Copy' menu item. 

*/ 

(HMenu, 

/* Handle of menu window. 

V 

MM SETITEMATTR, 

/* Set attribute of menu item. 

*/ 

MPFROM2SHORT 

(ID COPY, 

/* ’Copy' menu item. 

*/ 

TRUE), 

/* Include submenus. 

*/ 

MPFROM2SHORT 

(MIA DISABLED, 

/* Disabled attribute. 

*/ 


/* Disable only if block not marked. 

V 

BlockMarked ? 

0 ; MIA DISABLED)); 


WinSendMsg 

/* Set attribute of 'Paste' menu item*/ j 

(HMenu, 

/* Handle of menu window. 

*/ 

MM SETITEMATTR, 

/* Set attribute of menu item. 

*/ 

MPFROM2SHORT 

(ID PASTE, 

/* 'Paste' menu item. 

*/ 

TRUE), 

/* Include submenus. 

*/ 

MPFROM2SHORT 1 

(MIA DISABLED, 

/* Disabled attribute. 

*/ 


/* Disable if no data in clipboard. 

V 

ClipData ? 0 : 

MIA DISABLED)); 


return FALSE; 

case ID_SEARCH: 

/* 'Search' submenu. 

V 

WinSendMsg 

/* Set attribute of 'Find Next' item 

.*/ 

(HMenu, 

/* Handle of menu window. 

*/ 

MM SETITEMATTR, 

/* Set attribute of menu item. 

*/ 

MPFROM2SHORT 

(ID FINDNEXT, 

/* 'Find Next' menu item. 

*/ 

TRUE), 

/* Include submenus. 

*/ 

MPFROM2SHORT 

(MIA DISABLED 

/* Disabled attribute. 

V 


/* Disable if no search string given 

• V 

FindString [O' 

? 0 : MIA DISABLED)); 


return FALSE; 

case ID_OPTIONS: 

/* Options submenu. 

*/ 

/* Set menu item text according to current insert status. 

*/ 

WinSendMsg 

(HMenu, 

/* Menu handle. 

*/ 

MM SETITEMTEXT, 

/* Set item text. 

*/ 

MPFROM2SHORT (ID INSERT,0), /* ID of item. 

*/ 

Insert ? (MPARAM)(PCH)"Overwrite Mode\tIns" /* Text. 

*/ 

: (MPARAM)(PCH)"Insert Mode\tIns"); 


return FALSE; 

default: 
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return FALSE; 
} /* end switch */ 
} /* end InitMenu */ 


MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 
{ 


register int Line; 

/* 

Loop counter. 

*/ 

HPS HPresSpace; 

/* 

Presentation space handle. 

*/ 

RECTL Rect; 

/* 

Holds coordinates of rectangle. 

*/ 

SHORT StartLine; 

/* 

First file line to paint. 

*/ 

SHORT StopLine; 

/* 

Last line to paint. 

*/ 

POINTL Start; 

/* 

Starting position to print string. 

V 

SHORT LineLength; 

/* 

Length of each line displayed. 

V 

HPresSpace = WinBeginPaint 



(hwnd, 

/* 

Window handle. 

V 

0 , 

/* 

Handle of PS to have clipping region set. 

V 

&Rect); 

/* 

Address of struct, to set to invalid region. 

V 

GpiCreateLogFont 

/* 

Create a logical font for presentation space*/ 

(HPresSpace, 

/* 

Presentation space handle. 

*/ 

(PSTR8)NULL, 

/* 

Logical font name; none. 

V 

ID_COURIER, 

/* 

Local font ID; define a constant. 

*/ 

SFontAttributes) ; 

/* 

Struct, specifying font from GpiQueryFonts. 

*/ 

GpiSetCharSet 

/* 

Make logical font the current character set. 

■ */ 

(HPresSpace, 

/* 

Presentation space handle. 

*/ 

ID_COURIER); 

/* 

Local font ID. 

*/ 

WinFillRect 




(HPresSpace, 

/* 

Presentation space handle. 

V 

&Rect, 

/* 

Structure containing window coordinates. 

*/ 

CLR_WHITE); 

/* 

Color to use (white). 

*/ 

GpiSetColor 




(HPresSpace, 

/* 

Presentation space handle. 

V 

CLR BLACK); 

/* 

Color to use; black. 

V 


StartLine = TopLine + (yWin - (SHORT)Rect.yTop) / yCharTot; 

StopLine = min (LastLine, TopLine + (yWin - (SHORT)Rect.yBottom) 

/ yCharTot); 

Start.y = yWin - yCharTot * (StartLine - TopLine + 1) + yCharDesc; 
Start.x = xChar * (-FirstCol); 

for (Line = StartLine; Line <= StopLine; ++Line, Start.y -= yCharTot) 

{ 

if ((LineLength = GetLineLength (Line)) == 0) 
continue; 


GpiCharStringAt /* Prints string at given position. */ 

(HPresSpace, /* Presentation space handle. */ 

&Start, /* Structure containing starting position.*/ 

(LONG)LineLength, /* Number of characters to print. */ 

GetLineAddr (Line));/* Address of line. */ 
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} 


WinEndPaint (HPresSpace) ; 
return FALSE; 

} /* end Paint */ 

MRESULT EXPENTRY SetFocus (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 


if (LONGFROMMP (mp2)) 

f 

/* Client window RECEIVING 

focus. 

*/ 

{ 

WinCreateCursor 

/* Create a new cursor. 


*/ 

(hwnd, 

/* Client window handle. 


*/ 

(CursorCol - FirstCol) 

* xChar, /* x position of 

cursor. 

V 

yWin - (CursorLine - TopLine + 1) * yCharTot, /* y 

position. 

V 

0 , 

/* x size of cursor: nominal border 

V 

yCharTot, 

/* y size of cursor. 


V 

CURSOR SOLID | 

/* Solid cursor. 


V 

CURSOR FLASH, 

/* Blinking cursor. 


V 


NULL); /* Clipping rectangle; entire window.*/ 

WinShowCursor /* Make cursor visible. */ 

(hwnd, /* Client window handle. */ 

TRUE); /* Show it! */ 

} 

else /* Client window LOSING focus. */ 

WinDestroyCursor (hwnd); 

ret.urn FALSE; 

} /* end SetFocus */ 


MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

( 

ini: Update = 0 ; 

yWin = SH0RT2 FROMMP (mp2) ; 
xWin = SHORT1FR0MMP (mp2); 

/* Scroll window if necessary so that cursor position is visible. */ 

if (CursorLine >= TopLine + yWin / yCharTot) 

{ 

TopLine = CursorLine - yWin / yCharTot + 1; 

Update = 1; 

) 

if (Cursored >= FirstCol + xWin / xChar) 

{ i 

FirstCol = Cursored - xWin / xChar + 1; 

Update = 1; 

} 

if (Update) 
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WinlnvalidateRect 

/* 

Invalidate entire window. 

*/ 


(hwnd, 

/* 

Client window handle. 

*/ 


0 , 

/* 

Rectangle: 0 means whole window. 

*/ 


FALSE); 

/* 

Do not automatically include children. 

*/ 

/* 

Re-create the cursor if client window has focus. 

V 

if 

(hwnd == WinQueryFocus 


/* Does client have focus? 

*/ 


(HWND DESKTOP, 


/* Must give desktop handle. 

*/ 


FALSE)) 



/* Do not lock window. 

V 


( 

WinDestroyCursor 

(hwnd); 

/* 

Destroy existing cursor. 

*/ 


WinCreateCursor 


/* 

Create a new cursor. 

*/ 


(hwnd, 


/* 

Client window handle. 

V 


(CursorCol - 

FirstCol) 

* xChar, /* x position of cursor. 

V 


yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. 

*/ 


0 , 


/* 

x size of cursor: nominal border. 

*/ 


yCharTot, 


/* 

y size of cursor. 

V 


CURSOR SOLID 

i 

/* 

Solid cursor. 

*/ 


CURSOR FLASH 


/* 

Flashing cursor. 

V 


NULL); 


/* 

Clipping rectangle: entire window 

.*/ 


WinShowCursor 


/* 

Make cursor visible. 

V 


(hwnd, 


/* 

Client window handle. 

*/ 


TRUE); 

) 


/* 

Show it! 

*/ 

TopLineMax = max (0,LastLine - yWin / 

yCharTot + 1) ; 



TopLine = min (TopLine,TopLineMax); 


WinSendMsg /* Adjust range/position of slider. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0) , /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable scroll bar if scrolling is possible. */ 

(HVScroll, /* Recipient handle (vertical scroll bar).*/ 

TopLineMax ? TRUE : FALSE); /* Enable only if max. 1= 0. */ 

FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 

FirstCol = min (FirstCol, FirstColMax); 

WinSendMsg /* Adjust range/position of slider. */ 

(HHScroll, /* Recipient handle: horizontal scroll bar*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (FirstCol, 0), /* Position. */ 

MPFROM2SHORT (0, FirstColMax)); /* Range. */ 


return FALSE; 

} /* end Size */ 

MRESULT EXPENTRY VirtKey (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 
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if (NewCursorCol > FirstCol + xWin / xChar - 1) 

{ 

NewFirstCol = NewCursorCol - xWin / xChar + 1; 

Update = 1; 

} 

else if (NewCursorCol < FirstCol) 

{ 

NewFirstCol = NewCursorCol; 

Update = 1; 

} 

if (Update) 

WinSendMsg /* Scroll window to new position. */ 

(hwnd, 

WM_HSCROLL, 

OL, 

MPFR0M2 SHORT (NewFirstCol, 

SB_SLIDERPOSITION)); 

CursorCol = NewCursorCol; 
break; 

case VK_DELETE; /* Delete key. */ 

/*** Set global 'Modified' flag. ***********************************/ 
Modified = 1; 

/* Adjust file buffer if necessary. V 

if (LastCursorLine != CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine; 

} 

if (DeleteChar (CursorLine,CursorCol)) 

{ 

/* Deletion successful — invalidate update region. */ 

Rect.xLeft = (CursorCol - FirstCol) * xChar; 

Rect.xRight = min 

((GetLineLength (CursorLine) + 1 - FirstCol) * xChar, 
xWin); 

Rect.yBottom = yWin - (CursorLine - TopLine +1) * yCharTot; 
Rect.yTop = Rect.yBottom + yCharTot; 

WinlnvalidateRect /* Invalidate region to be updated. */ 
(hwnd, 

&Rect, 

FALSE); 

WinUpdateWindow (hwnd) ; /* Force client window update. */ 

} 

return TRUE; 

case VK_F9: /* F9 key: delete line. */ 
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/*** 


Set global 'Modified' flag. ***********************************/ 
Modified = 1; 


/* If modifying new line, must place line in temporary buffer.*/ 
if (LastCursorLine 1= CursorLine) 

{ 

ReleaseTempBuf (LastCursorLine); 

GetTempBuf (CursorLine); 

LastCursorLine = CursorLine? 

} 

/* Delete line containing the cursor. */ 

DeleteLine (CursorLine); 

/* Adjust 'TopLineMax' / scroll bar range for new file length.*/ 


TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

WinSendMsg 

(HVScroll, /* Recipient handle. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFR0M2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow 

(HVScroll, /* Recipient handle. */ 

TopLineMax ? 1 : 0); /* Enable only if max.!= 0*/ 

/* Invalidate 'CursorLine' and all lines below. */ 


Rect.xLeft = 0; 

Rect.xRight = xWin? 

Rect.yTop = yWin - (CursorLine - TopLine) * yCharTot? 

Rect.yBottom = 0 ? 

WinlnvalidateRect /* Invalidate section to be modified. */ 

(hwnd, /* Handle of client window. */ 

&Rect, /* Rectangle to be added to invalid region. */ 

FALSE); /* No descendants w/ WS_CLIPCHILDREN. */ 

WinUpdateWindow (hwnd); /* Force updating of client window. */ 

return TRUE; 

default: /* All other virtual codes. */ 

return FALSE ? 

} /* end virtual key switch */ 


WinCreateCursor /* Set position of cursor. */ 

(hwnd, /* Client window handle. */ 

(Cursored - FirstCol) * xChar, /* x position of cursor. */ 

yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 

0, /* x size of cursor: n/a. */ 

0 , /* y size of cursor: n/a. */ 

CURS0R_SETP0S, /* Option to set position only. */ 

NULL); /* Clipping rectangle: n/a */ 


return TRUE; 
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* end VirtKey */ 


MRESULT EXPENTRY VScroll (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

SHORT Delta; /* Amount to scroll. */ 

switch (SHORT2FROMMP (mp2)) /* Switch on code for scrolling event. */ 

case SB_LINEUP: 

Delta = -1; 
break; 

case SB_LINEDOWN: 

Delta = 1; 
break; 

case SB_PAGEUP: 

Delta = -yWin / yCharTot; 
break; 

case SB_PAGEDOWN: 

Delta = yWin / yCharTot; 
break; 

case SB_SLIDERPOSITION: 

Delta = SHORT1FR0MMP (mp2) - TopLine; 
break; 
default: 

Delta = 0; 
break; 

Delta = max (-TopLine, min (Delta,TopLineMax - TopLine)); 

if (Delta) 

•1 

TopLine += Delta; 

CursorLine += Delta; 


WinShowCursor 

/* Hide the cursor. 

V 

(hwnd, 

/* Client window handle. 

*/ 

FALSE); 

/* Hide it! 

*/ 

WinScrollWindow 

/* Scroll window vertically. 

V 

(hwnd, 

/* Handle of client window. 

*/ 

0, 

/* Horizontal scroll amount. 

*/ 

yCharTot * Delta, 

/* Vertical scroll amount. 

V 

0, 

/* Must be 0. 

*/ 

0, 

/* Must be 0. 

*/ 

0, 

/* Must be 0. 

*/ 

0, 

/* Must be 0. 

*/ 

SW_INVALIDATERGN); 

/* Invalidate ’’exposed" region. 

*/ 

WinUpdateWindow 

/* Force window update. 

V 

(hwnd); 

/* Handle of client window. 

V 

WinSendMsg 

/* Adjust vertical scroll bar. 

V 

(HVScroll, 

/* Handle to vertical scroll bar. 

V 

SBM SETPOS, 

/* Set position of slider. 

V 


• Figure S38: 

The C source code file for the example program (continued) 



• 428 Programmer's Guide to the OS/2 Presentation Manager 


MPFROM2SHORT (TopLine,0),/* Current position. */ 

0); /* Second parameter n/a. */ 


WinCreateCursor /* Set position of cursor. */ 

(hwnd, /* Client window handle. */ 

(Cursored - FirstCol) * xChar, /* x position of cursor. */ 

yWin - (CursorLine - TopLine + 1) * yCharTot, /* y position. */ 


0, 

/* 

x size of cursor: n/a. 

*/ 

o, 

/* 

y size of cursor: n/a. 

*/ 

CURSOR SETPOS, 

/* 

Option to set position only. 

*/ 

NULL) ; 

/* 

Clipping rectangle: n/a 

*/ 


WinShowCursor 

/* 

Restore cursor 

■ visibility. 

*/ 

(hwnd, 

/* 

Client window 

handle. 

V 

TRUE); 

/* 

Show it! 


V 


} /* end if (Delta) */ 


return FALSE; 


} /* end VScroll */ 


/*** Dialog window procedures, ^fc**********************************************/ 


MRESULT EXPENTRY AboutProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


/ 


Process dialog messages for the 'About' dialog box. 


( 

switch (msg) 

{ 

/*** process WM_COMMAND messages sent by 'About' dialog box controls, 
case WM COMMAND: 


k k k / 


switch (COMMANDMSG(&msg)->cmd) 

{ 

/kkk user clicked on 'Ok' button or pressed Enter key. ********/ 
case DID_OK: 

/kkk user clicked on 'Cancel' button or pressed Escape key. ***/ 
case DID_CANCEL: 

WinDismissDlg (hwnd,TRUE); 
return FALSE; 

default: 

return FALSE; 

} 

default: 

/* Execute default processing for all other messages. */ 

return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 
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} /* end AboutProc */ 

MRESULT EXPENTRY FindProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

char Buffer [2]? /* Holds first character of entered file name. */ 

USHORT Update = FALSE? /* Flag indicates whether window update needed.*/ 

switch (msg) 

/* process WM_COMMAND messages sent by dialog controls. *****************/ 
case WM__COMMAND: 

switch (COMMANDMSG(&msg)->cmd) 

/*** User clicked on 'Find' button or pressed Enter key. ******/ 
case DID_OK: 

/* Obtain text from ’Find:' edit box. */ 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_FINDEDIT), 
sizeof (FindString), 

Findstring); 

/* If search string empty, return immediately. */ 

if (FindString [0] == '\0') 
return FALSE? 

/* Search for string. V 

if (SearchBuf (FindString, SCursorLine, SCursorCol) =- 
FALSE) 

/* Display message if string not found. */ 

WinMessageBox 

(HWND_DESKTOP, 

hwnd, /* Note: parent is dialog window*/ 

•'String not found", 

"PM Text Editor", 

0, 

MB_0K | 

MB_ICONASTERISK)? 

/* Remove dialog box. */ 

WinDismissDlg (hwnd, FALSE)? 
return FALSE? 

} 

/* Adjust 'TopLine' for new cursor position. */ 

if (CursorLine < TopLine || 

CursorLine >= TopLine + yWin/yCharTot) 

TopLine = max (0,CursorLine - (yWin/yCharTot)/2)? 
TopLine = min (TopLine,TopLineMax)? 

Update = TRUE? 
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} 

/* Adjust 'FirstCol' for new cursor position. */ 

if (Cursored < FirstCol | | 

CursorCol >= FirstCol + xWin / xChar) 

( 

FirstCol = max (0,CursorCol - (xWin/xChar)/2); 
FirstCol = min (FirstCol,FirstColMax); 

Update = TRUE; 

} 

/* Remove dialog box, returning flag indicating */ 

/* whether window must be updated. */ 

WinDismissDlg (hwnd, Update); 
return FALSE; 

/*** User clicked on 'Cancel' button or pressed Escape key. */ 
case DID_CANCEL: 

/* Remove dialog box. */ 

WinDismissDlg (hwnd,FALSE); 
return FALSE; 

default: 

return FALSE; 

} 

/*** Process WM_CONTROL messages sent by edit field. ********************/ 

case WM_C0NTR0L: 

switch (SHORT1FROMMP (mpl)) 

{ 

/*** Message sent by edit box. ********************************/ 
case ID_FINDEDIT: 

switch (SHORT2 FROMMP (mpl)) 

{ 

/*** user altered the text. *************************/ 
case EN_CHANGE: 

/* Get new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable 'Find' button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

Buffer [0]); 
return FALSE; 
default: 

return FALSE; 

} 

default: 

return FALSE; 
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} 

/*** process WM_INITDLG message sent when dialog box first displayed. ***/ 
case WM_INITDLG: 

/* Display initial value of 'FindString' in edit box. */ 

WinSetWindowText 

(WinWindowFromID (hwnd,ID_FINDEDIT), 

FindString); 

default: t 

/* Execute default processing for all other messages. / 

return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 

} /* end FindProc */ 

MRESULT EXPENTRY GotoProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

char NumberBuf [33]; 
char Buffer [2]; 

SHORT LineNumber; 

switch (msg) 

/*** Process WM_COMMAND messages sent by dialog controls. ***************/ 
case WM_COMMAND: 

switch (COMMANDMSG(&msg)->cmd) 

/*** user clicked on 'Go to' button or pressed Enter key. *****/ 
case DID_OK: 

/* Obtain text from 'Go to Line' edit box. */ 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_GOTOEDIT), 
sizeof (NumberBuf), 

NumberBuf); 

/* Convert to numeric value and continue if > 0. */ 

LineNumber = atoi (NumberBuf); 
if (LineNumber <= 0) 
return FALSE; 

/* Set global cursor and window position variables. */ 
—LineNumber; 

CursorLine = min (LastLine,LineNumber); 

TopLine = max (0,CursorLine - (yWin/yCharTot)/2); 
TopLine = min (TopLine,TopLineMax); 

CursorCol = FirstCol = 0; 

/* Remove dialog box. */ 
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WinDismissDlg (hwnd, TRUE); 
return FALSE; 

/*** user clicked on ’Cancel' button or pressed Escape key. */ 
case DID__CANCEL: 

/* Remove dialog box. */ 

WinDismissDlg (hwnd,FALSE); 
return FALSE; 

default: 

return FALSE; 

} 

/*** Process WM_CONTROL messages sent by edit field. ********************/ 

case WM_CONTROL: 

switch (SH0RT1FR0MMP (mpl)) 

{ 

case ID_GOTOEDIT: 

switch (SH0RT2 FROMMP (mpl)) 

{ 

/*** user altered the text. *************************/ 
case EN_CHANGE: 

/* Get new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable ’Go to' button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

Buffer [0]); 
return FALSE; 
default: 

return FALSE; 

} 

default: 

return FALSE; 

} 

/*** process WM_INITDLG message sent when dialog box first displayed. ***/ 
case WM_INITDLG: 

/* Initially disable 'Go to' button (until text entered). */ 

WinEnableWindow 

(WinWindowFromID (hwnd, DID_0K), 

FALSE); 
return FALSE; 

default: 

return WinDefDlgProc (hwnd, msg, mpl, mp2); 
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} /* end GotoProc */ 
VOID InitDlg (HWND hwnd); 


/* Initializes the 'Open' dialog box. 


MRESULT EXPENTRY OpenProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* 

Processes messages sent to 'Open' dialog box. 

*/ 

{ 

SHORT Selectlndex; /* Index of selected item in 'Open' list box. */ 

char Buffer [16]; /* Temporary storage for text. */ 

static char FilePath [PATHLENGTH]; /* Holds file path string. */ 

USHORT Reply; /* Response from message box. */ 

switch (msg) 

( 

/*** Process WM_COMMAND messages sent by dialog controls. ***************/ 

case WM_COMMAND: 

switch (COMMANDMSG(&msg)->cmd) 

{ 

/*** user clicked on 'Open' button or pressed Enter key. ******/ 
case DID_OK: 

/* Obtain text from edit box. */ 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_OPENEDIT), 
sizeof (FilePath), 

FilePath); 

/* If a file name is entered, try to read the file. */ 
if (FilePath [0]) 

{ 

if (Modified) /* File is modified. */ 

{ 

/* Warn user and elicit response on */ 

/* saving file. */ 

Reply = WinMessageBox 
(HWNDJDESKTOP, 
hwnd, 

"File Unsaved; Save?", 

"PM Text Editor", 

0, 

MB_YESNO | 

MB_ICONQUESTION); 

/* If reply is Yes, send a 'Save' menu */ 

/* message to client. */ 

if (Reply == MBID_YES) 

/* Repeat message until file */ 

/* successfully saved. */ 

while (Modified) 
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WinSendMsg 

(HClient, 

WM_COMMAND, 

MPFR0M2SHORT (ID_SAVE, 0), 

0L) ; 

} /* end if Modified */ 

ReleaseFile (); /* Free current heap. */ 

/* Read the new file. */ 

if (ReadFile (FilePath)) 

{ 

/* Warn user if read error occurred. */ 

WinMessageBox 

(HWND_DESKTOP, 

hwnd, 

"Error — Cannot Read File", 

"PM Text Editor", 

0, 

MB_OK | 

MB_ICONASTERISK) ; 


FileName [0] = »\0 1 ; /* Null file name. */ 

NewFile (); /* New file instead.*/ 

} 

/* File was successfully read. */ 

else 

/* Store fully qualified path name. */ 

Qualify (FilePath, FileName); 

ShowFileName (); /* Display name in title bar. */ 
Modified =0? /* Reset modified flag. */ 

InitWindow (); /* Set window/cursor values. */ 

/* Remove the dialog box. */ 

WinDismissDlg 

(hwnd, /* Handle of dialog window. */ 

TRUE); /* Code returned by WinDlgBox. */ 

return FALSE; 

} 


return FALSE; 

/*** User clicked on 'Cancel' button or pressed Escape key. ***/ 
case DID_CANCEL: 

/* Remove the dialog box. */ 

WinDismissDlg 

(hwnd, /* Handle of dialog window. */ 

TRUE); /* Code returned by WinDlgBox. */ 

return FALSE; 

default: 

return FALSE; 
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/*** process WM_CONTROL messages sent by edit box or list box. **********/ 

case WM_CONTROL: 

switch (SHORT1FR0MMP (mpl)) 

{ 

/*** Message sent by edit box. ********************************/ 
case ID_OPENEDIT: 

switch (SHORT2 FROMMP (mpl)) 

{ 

/*** User altered the text. *************************/ 
case EN_CHANGE: 

/* Get the new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2 , 

Buffer); 

/* Enable 'Open' button if text present. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

Buffer [0]); 
return FALSE; 
default: 

return FALSE? 

} 

/*** Message sent by list box. ********************************/ 
case ID_OPENLIST: 

/* Get index of selected item. */ 

Selectlndex = (SHORT) WinSendDlgltemMsg 
(hwnd, 

ID_OPENLIST, 

LM_QUERYSELECTION, 

0L, 

0L) ? 

/* Get text belonging to selected item. */ 

WinSendDlgltemMsg 
(hwnd, 

ID_OPENLIST, 

LM_QUERYITEMTEXT, 

MPFROM2SHORT (Selectlndex, sizeof (Buffer)), 
MPFROMP (Buffer))? 

/* Branch on code for specific event. */ 

switch (SHORT2 FROMMP (mpl)) 

{ 

/* User pressed Enter key or double clicked. */ 
case LN_ENTER: 

/* Item is for a drive letter. */ 

if (Buffer [0] == '[' && 

Buffer [1] == '-') 

{ 
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/* Change to specified drive. */ 

DosSelectDisk (Buffer [2] - 64); 

/* Update dialog box data. */ 

InitDlg (hwnd); 

} 

/* Item is for a directory. */ 

else if (Buffer [0] == '[’) 

{ 

/* Null terminate after directory. */ 
Buffer [strlen (Buffer) - 1] = '\0'; 

/* Change to new directory. */ 

DosChDir 

(Buffer + 1, 

0L) ; 

/* Update dialog box data. */ 

InitDlg (hwnd); 

} 

/* Item is a file name. */ 


else if (Buffer [0]) 

{ 

/* Save the file by sending message. */ 
WinSendMsg 

(hwnd, /* Dialog window hand.*/ 
WM_COMMAND, /* Message ID. */ 
MPFROM2 SHORT (DID_OK,0), 

0L) ; 

/* Remove the dialog box. */ 

WinDismissDlg (hwnd, TRUE); 
return FALSE; 

) 

return FALSE; 

/* New item is selected (highlighted). */ 

case LN_SELECT: 

/* Null string for drive or directory. */ 
if (Buffer [0] == '[') 

Buffer [0] = '\0'; 

/* Place selected text in edit box. */ 

WinSetWindowText 

(WinWindowFromID (hwnd,ID_OPENEDIT), 
Buffer); 
return FALSE; 

default: 

return FALSE; 

} 

default; 

return FALSE; 

} 

/*** Process WM_INITDLG message sent when dialog box first displayed. ***/ 
case WM INITDLG: 
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/* Expand text limit in edit box to full file path length. */ 
WinSendDlgltemMsg 
(hwnd, 

ID_OPENEDIT, 

EM_SETTEXTLIMIT, 

MPFR0M2 SHORT (PATHLENGTH,0) , 

o) ; 

/* initially disable the 'Open' button until text is entered. */ 
WinEnableWindow 

(WinWindowFromID (hwnd, DID_OK), 

FALSE)? 

/* Display initial directory and list box data. */ 

InitDlg (hwnd); 

return FALSE; 


default: 

/* Execute default processing for all other messages, 
return WinDefDlgProc (hwnd, msg, mpl, mp2)? 

} /* end switch */ 

} /* end OpenProc */ 

VOID InitDlg (HWND hwnd) 


*/ 


/* 

*/ 


Called by 'OpenProc' to display current data in 'Current Directory' field 
and list box of 'Open’ dialog box. 


( 

register int Drive; 

USHORT DriveNumber; 

ULONG LogicalDrives; 
char Buffer [PATHLENGTH]; 
HDIR HSearch = 1; 
FILEFINDBUF FindBuf; 
USHORT FileCount = 1; 
char *PtrCh; 


/* Disk drive letter. */ 

/* Disk drive number. */ 

/* Mapping of installed drives. */ 

/* Holds file paths. */ 

/* OS/2 file search handle. */ 

/* Structure for file searches. */ 
/* Count files to find/found. */ 
/* Temporary character pointer. */ 

/*** Obtain current default drive path. **************************************/ 
GetPath (Buffer, sizeof (Buffer)); 

/*** Display current drive and directory path in 'Current Directory' field. **/ 
WinSetWindowText 

(WinWindowFromID (hwnd, ID_OPENCD), /* ID of Current / 

/* Directory' field. */ 

Buffer); /* Buffer containing text to display. */ 

/*** obtain current default disk and mapping of installed drives. *********** / 

DosQCurDisk . . 

(&DriveNumber, /* Receives number of current drive. */ 
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^LogicalDrives); 


/* Receives mapping of installed drives. 


*/ 

/*** clear all existing entries from the list box. ***************************/ 
WinSendDlgltemMsg /* Send message to dialog item. */ 

(hwnd, /* Handle of dialog window. */ 

ID_OPENLIST, /* ID of list box. */ 

LM_DELETEALL, /* Delete all entries. */ 

°' /* mpl: not used. */ 

°) ; /* mp2: not used. */ 

/*** Insert drive letters into list box. *************************************/ 
for (Drive = 'A'; Drive <= »z'; ++Drive) 7 

if (LogicalDrives & l) 

{ 

sprintf (Buffer,"[-%c~]", Drive) ; 

WinSendDlgltemMsg /* Send message to dialog item. 

(hwnd, /* Handle of dialog window. 

ID_OPENLIST, /* id of list box. 

LM_INSERTITEM, /* Insert an item. 

MPFR0M2SH0RT (LIT_SORTASCENDING, 0), /* Ascending sort 

/* order. 

MPFROMP (Buffer)); /* Address of item text. 

} 

LogicalDrives >>= l; 


V 
*/ 
*/ 
*/ 

V 
*/ 
*/ 


/*** Insert directories and files into list box. *****************************/ 




/* Find first directory or file. 

DosFindFirst 

("*•*"/ /* Any name. *✓ 

&HSearch, /* Receives handle for search. */ 

0x0°l°, /* Subdirectories and normal files. */ 

.indBuf ,. /* Receives information on matching file. */ 

sizeof (FmdBuf) , /* Length of buffer to receive information*/ 


&FileCount, 

0L) 

/*_Process each matching file, 
while (FileCount) 

{ 


/* Count of files to find/files found. 
/* Reserved: must be 0. 


*/ 

*/ 

*/ 

V 


/* If match is a directory, but NOT '.', insert it in list box. 
if (FindBuf.attrFile & 0x0010 && 

! (FindBuf.achName [0] == 1 .' && FindBuf.achName [1] == 1 \0 1 ) ) 

sprintf (Buffer,»[%s] M ,FindBuf.achName); 

WinSendDlgltemMsg /* See above. */ 

(hwnd, / 

ID_OPENLIST, 

LM_INSERTITEM, 

MPFROM2SHORT (LIT_SORTASCENDING, 0), 

MPFROMP (Buffer));' 

> 

/* If match is a normal file, insert only if it has the .TXT or */ 
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© 


/* .C extension. 

else if (strcmp ((PtrCh = Extension (FindBuf.achName)), 
|| strcmp (PtrCh,"C") == 0) 

WinSendDlgltemMsg /* See above. 

(hwnd, 

IDOPENLIST, 

LM_INSERTITEM, 

MPFROM2SHORT (LIT_SORTASCENDING, 0), 

MPFROMP (FindBuf.achName)); 


/* Find NEXT matching file. 
DosFindNext 

(HSearch, /* 

&FindBuf, /* 


/* Search handle returned by DosFindFirst.*/ 
/* Receives information on matching file. */ 


sizeof (FindBuf), /* Length of receiving buffer. 


SFileCount); 


/* Returns number of matching files left. */ 


} /* end InitDlg */ 

MRESULT EXPENTRY SaveasProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* 

Processes dialog messages for the ’Save As’ dialog box. 

*/ 

char FilePath [PATHLENGTH]; /* Holds file path. */ 

char CurDir [PATHLENGTH + 22]; /* Holds contents of 'Current Directory'.*/ 
char Buffer [2]? /* Holds first character of entered file name. */ 

switch (msg) 

/*** process WM_COMMAND messages sent by dialog controls. ********************/ 
case WM_COMMAND: 

switch (COMMANDMSG(&msg)->cmd) 

/*** user clicked on 'Save' button or pressed Enter key. ******/ 
case DID_0K: 

/* Obtain text from 'Save As' edit box. */ 

WinQueryWindowText 

(WinWindowFromID (hwnd, ID_SAVEASEDIT), 
sizeof (FilePath), 

FilePath); 

/* If path string not empty, save file/remove dialog*/ 
if (FilePath [0]) 

( 

/* Save under the new name. */ 

if (SaveFile (FilePath) == FALSE) 

/* Display error message if save failed. */ 
WinMessageBox 
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(HWND_DESKTOP, 

hwnd, 

"Error — Cannot Save File", 

"PM Text Editor", 

0, 

MB_OK | 

MB_ICONASTERISK); 

else 

{ 

/* Store fully qualified path name. */ 

Qualify (FilePath, FileName); 

/* Display the new name in title bar. */ 

ShowFileName (); 

/* Reset 'Modified' flag. */ 

Modified = 0; 

} 

/* Remove dialog box. */ 

WinDismissDlg (hwnd, TRUE); 
return FALSE; 

} 

return FALSE; 

/*** User clicked on 'Cancel' button or pressed Escape key ***/ 
case DID__CANCEL: 

/* Remove the dialog box. */ 

WinDismissDlg (hwnd,TRUE); 
return FALSE; 

default: 

return FALSE; 

} 

/*** Process WM_C0NTR0L messages sent by edit box. **********************/ 

case WM_C0NTR0L: 

switch (SHORT1FR0MMP (mpl)) 

{ 

/*** Message sent by edit box. ********************************/ 
case ID_SAVEASEDIT: 7 

switch (SHORT2 FROMMP (mpl)) 

{ 

/*** User altered the text. *************************/ 
case EN_CHANGE: 

/* Get new text. */ 

WinQueryWindowText 
((HWND) mp2, 

2, 

Buffer); 

/* Enable 'Save' button if text present. */ 
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WinEnableWindow 

(WinWindowFromlD (hwnd, DID_OK), 

Buffer [0]); 
return FALSE; 
default: 

return FALSE; 

} 

default: 

return FALSE; 

} 

/*** Process WM_INITDLG message sent when dialog box first displayed. ***/ 
case WM_INITDLG: 

/* Expand text limit in edit box to full file path length. */ 
WinSendDlgltemMsg 
(hwnd, 

ID_SAVEASEDIT, 

EM_SETTEXTLIMIT, 

MPFROM2SHORT (PATHLENGTH,0), 

0 ) ? 

/* Initially disable the 'Save' button until text is entered. */ 
WinEnableWindow 

(WinWindowFromlD (hwnd, DID_OK), 

FALSE); 


/* Obtain current directory path. */ 

GetPath (FilePath, sizeof (FilePath)); 

/* Format string for 'Current Directory' field. */ 

sprintf (CurDir,"Current Directory: %s",FilePath); 

/* Display string in 'Current Directory' field. V 

WinSetWindowText 

(WinWindowFromlD (hwnd, ID_SAVEASCD), /* ID of */ 

/* 'Current Directory' field. */ 
CurDir); /* String to display. */ 

return FALSE; 

default: 

/* Execute default processing for all other messages. */ 

return WinDefDlgProc (hwnd, msg, mpl, mp2); 

} 


} /* end SaveasProc */ 


/*** Function used by the window procedures. ********************************/ 

void NotYet (char ^Message) 

{ 

char Buffer [60]; 
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/* Format message. 

sprintf (Buffer,"Not Yet Implemented: %s",Message); 


WinMessageBox 

(HWND_DESKTOP, 

HFrame, 

Buffer, 

"PM Text Editor", 

0 , 

MB_0K | 

MB__ICONASTERISK) ; 
} /* end NotYet */ 


/* Display a message box. 

/* Handle of parent — try frame. 
/* Handle of owner. 

/* Message text. 

/* Caption. 

/* Help window ID: not needed. 

/* Display an 'OK' button. 

/* Display an exclamation. 


V 

*/ 

V 

*/ 

V 

*/ 

V 

V 


/*** Buffer-management module ************************************************/ 
#define MAXLINES 4096 /* Maximum number of lines in file buffer.*/ 


static struct 

{ 


PCH LineAddress; 
unsigned char LineLength; 

} 

LineTable [MAXLINES]; 

static char LineBuffer [LINEBUFSIZ]; 
static unsigned LineSelector; 
static unsigned LineOffset; 
static SEL HeapSelector; 


/* Stores information on each line. 

/* Far address of block containing line. 
/* Length of line (includes \n and \0). 


/* Temporary line buffer. 

/* Selector for 'LineBuffer*. 
/* Offset for 'LineBuffer'. 

/* Selector of heap segment. 


V 

V 

V 


V 

V 

V 

V 


void Buflnit (void) 
{ 

PCH FarPtr; 


/* Initializes the buffer management module. 


V 


FarPtr = (char far *)LineBuffer; 
LineSelector = SELECTOROF (FarPtr); 
LineOffset = OFFSETOF (FarPtr); 

} /* end Buflnit */ 


int 


/* 


V 


DeleteChar 
(SHORT Line, 
SHORT Column) 


/* Deletes a character from 'LineBuffer'. 

/* Line containing character to be deleted. 
/* Number of character to be deleted. 


This function.deletes the indicated character from 'LineBuffer'. It 
returns TRUE if the buffer was modified, and FALSE if no action took 
place (i.e., the specified character was beyond the visible end of the 
line) . 


V 

V 

V 


{ 

/* Return FALSE if character is beyond visible length of line, 
if (LineTable [Line].LineLength <3 || 
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Column > LineTable [Line].LineLength - 3) 
return FALSE; 


/* Move all characters beyond deleted character 

one 

place left. 

V 

memmove 




(LineBuffer + Column, 

/* 

Target. 

*/ 

LineBuffer + Column + 1, 

/* 

Source. 

V 

LineTable [Line].LineLength - Column - 1); 

/* 

Number of bytes. 

*/ 


—LineTable [Line].LineLength; 


return TRUE; 

} /* end DeleteChar */ 


void DeleteLine (SHORT Line) 

/* 

Deletes the specified line ('Line', which must be the line currently 
containing the cursor) from the file buffer. 

V 

/* If line to be deleted is the last file line, merely truncate it. */ 

if (Line == LastLine) 

( 

LineBuffer [0] = '\n'; 

LineBuffer [1] = '\0'; 

LineTable [Line].LineLength = 2; 

} 

else 

/* Place the following line into 'LineBuffer'. */ 

GetTempBuf (Line + 1); 

/* Move all LineTable elements beyond deleted line down one element*/ 
memmove 

(SLineTable [Line], /* Target. */ 

ScLineTable [Line +1], /* Source. */ 

(LastLine - Line) * sizeof (LineTable [0])); /* Number bytes. */ 

—LastLine; 

} 

} /* end DeleteLine */ 


char *ErrorMessage (int ErrorNumber) 

/* 

Returns a string that describes the error code given by 'ErrorNumber'. 

*/ 

{ 

static char *MessageTable [] = 

{ 

"no error", 

"file open failure". 
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"file too large", 

"maximum lines exceeded", 

"heap memory allocation failed", 

"unidentified error" 

}; 

if (ErrorNumber >= sizeof (MessageTable) / sizeof (char *)) 

ErrorNumber = sizeof (MessageTable) / sizeof (char *) - 1; 

return MessageTable [ErrorNumber]; 

} /* end ErrorMessage */ 


PCH GetLineAddr (int Line) 

/* 

Returns the address of the file buffer line specified by 'Line'. 

V 

{ 

if (Line < 0 || Line > LastLine) 
return NULL; 

else 

return LineTable [Line].LineAddress; 

} /* end GetLineAddr */ 


SHORT GetLineLength (int Line) 

/* 

Returns the length of the file buffer line specified by 'Line'. 

V 

{ 

if (Line < 0 || Line > LastLine) 
return 0; 

else 

return LineTable [Line].LineLength - 2; 

} /* end GetLineLength */ 


void GetTempBuf /* Places specified line into 'LineBuffer'. */ 

(int Line) /* Number of line. */ 

/* 

This function: 

o Copies the string in the specified line into 'LineBuffer' 
o Frees the block formerly holding the string 
o Adjusts the address in 'LineTable' 

*/ 

{ 


/* Copy string into 'LineBuffer'. */ 

movedata /* Intersegment block copy.*/ 

(SELECTOROF (LineTable[Line].LineAddress), /* Source segment. */ 

OFFSETOF (LineTable[Line].LineAddress), /* Source offset. */ 

LineSelector, /* Target segment. */ 

LineOffset, /* Target offset. */ 
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LineTable [Line].LineLength); 


/* Bytes to copy. 


/* Release block formerly holding line, 
il: (WinFreeMem 

(HHeap, /* Handle of heap from 'WinCreateHeap'. 

(BYTE NEAR *)OFFSETOF (LineTable [Line].LineAddress), /* Offset. 

LineTable [Line].LineLength) /* Length of block to free. 

.!= NULL) 

sprintf (Message,"managing heap; line %d",_LINE_); 

ErrorQuit (Message); 

} 

LineTable [Line].LineAddress = MAKEP (LineSelector,LineOffset); 

} /* end GetTempBuf */ 


int InsertChar / 

(SHORT Line, / 

USHORT Character, / 

SHORT Column, / 

int Insert) / 

{ 

unsigned char LineLength; 


/* Inserts character into 'LineBuffer'. 
/* Number of line for insertion. 

/* Character to insert. 

/* Column position of character. 

/* Flag indicating overwrite mode. 


LineLength = LineTable [Line].LineLength; 

/* if line would exceed maximum line length, return without inserting. */ 
if (Column > LINEBUFSIZ —3 || LineLength >= LINEBUFSIZ && Insert) 
return FALSE; 

/* if column is at end of line (common case), use fast routine to insert*/ 
else if (Column == LineLength - 2) 

{ 

/* Copy ' \n' and '\0' to new position. V 

LineBuffer [Column + 2] = LineBuffer [Column + 1]; 

LineBuffer [Column + 1] = LineBuffer [Column]; 

LineBuffer [Column] = (char)Character; /* Write the character. */ 

-i-+LineTable [Line] .LineLength; 
return TRUE; 


/* If column is BEYOND end of line, must pad line with spaces, 
else if (Column > LineLength - 2) 

{ 

/* Copy '\n' and '\0' to new position. 

LineBuffer [Column + 2] = LineBuffer [LineLength - 1]; 
LineBuffer [Column + 1] = LineBuffer [LineLength - 2]; 


/* Fill line with spaces, 
memset 

(LineBuffer + LineLength - 2, 


/* Destination. 
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Column - LineLength + 2); 


/* Character to fill with. */ 
/* Number of repetitions. */ 

LineBuffer [Column] = (char)Character; /* Write the character. */ 

/* Adjust line length. */ 

LineTable [Line].LineLength = (unsigned char)Column + 3; 
return TRUE; 

} 

/* Otherwise, must insert character in middle of line. */ 

{ 

/* If insert mode is active, move all characters right of */ 

/* insertion point one space to the right. */ 

if (Insert) 

{ 

memmove /* Move block. */ 

(LineBuffer + Column +1, /* Target. */ 

LineBuffer + Column, /* Source. */ 

LineLength - Column); /* Number of bytes. */ 

++LineTable [Line].LineLength; 

} 

LineBuffer [Column] = (char)Character; /* Write the character. */ 


return TRUE; 

} 

} /* end InsertChar */ 


void InsertLine (SHORT Line, SHORT Column) 

/* 

Inserts a new line into the file buffer, immediately before character 
given by 'Column', within the line given by 'Line'. 

V 

{ 

NPCH HeapOffset; /* Holds 16-bit heap offset. */ 

PCH HeapPointer; /* Holds far pointer to heap base. */ 


/* Fatal error if maximum lines reached. */ 

if (++LastLine >= MAXLINES) 

{ 

sprintf (Message,"maximum lines reached; line %d", _LINE ); 

ErrorQuit (Message); 

} 

/* Adjust 'Column' to maximum position in line. */ 

if (Column > LineTable [Line].LineLength - 2) 

Column = LineTable [Line].LineLength - 2; 

/* Allocate a block for characters in line before 'Column'. */ 

HeapOffset = WinAllocMem 
(HHeap, 

Column + 2); 
if (HeapOffset == NULL) 
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sprintf (Message,"out of heap memory; line %d", _LINE_); 

ErrorQuit (Message); 

} 


/* Copy characters before 'Column' into new block. */ 

movedata /* Intersegment block copy. */ 

(Lineselector, /* Source: selector of 'LineBuffer'. */ 

LineOffset, /* Source: offset of 'LineBuffer'. */ 

HeapSelector, /* Target: selector of heap. */ 

(unsigned)HeapOffset, /* Target: offset of new block. */ 

Column); /* Number of characters to copy. */ 

/* Construct a far pointer to new block in heap. */ 

HeapPointer = MAKEP (HeapSelector,HeapOffset); 

/* Write newline and null to end of new line in heap. */ 

* (HeapPointer + Column) = 1 \n'; 

*(HeapPointer + Column + 1) = ' \0' ; 

/* Move character number 'Column' and all following characters to */ 

/* beginning of 'LineBuffer'. */ 

memmove /* Intrasegment block copy.*/ 

(LineBuffer, /* Target address. */ 

LineBuffer + Column, /* Source address. */ 

LineTable [Line].LineLength - Column); /* Bytes to move. */ 

LineTable [Line].LineLength -= (unsigned char)Column; 

/* Move all members of 'LineTable' one position toward end of table. */ 
memmove 

(SLineTable [Line + 1], /* Target. */ 

SLineTable [Line], /* Source. */ 

(LastLine - Line) * sizeof (LineTable [0])); /* Bytes to move. */ 

/* Assign address of new heap block to 'LineTable'. */ 

LineTable [Line].LineAddress = HeapPointer; 

LineTable [Line].LineLength = (unsigned char)(Column + 2); 


} /* end InsertLine */ 


int JoinLine (SHORT Line) 

/* 

Combines the line in the file buffer given by 'Line' with the previous 
line. 

*/ 

{ 

/* Return if 'Line' is the first in the file (no previous line). */ 

if (Line == 0) 

return FALSE; 

/* Return if combined length would exceed maximum line length. */ 

if (LineTable [Line].LineLength + LineTable [Line - 1].LineLength - 2 > 
LINEBUFSIZ) 
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return FALSE; 


/* Move existing characters in ’LineBuffer’ to right to make room for */ 
/* the characters from previous line. */ 
memmove 

(LineBuffer + LineTable [Line - 1].LineLength - 2, /* Target. */ 
LineBuffer, /* Source. */ 
LineTable [Line].LineLength); /* Number of bytes. */ 

/* Move the characters from previous line to beginning of ’LineBuffer’. */ 
movedata 

(SELECTOROF (LineTable [Line - 1].LineAddress), /* Source. */ 
OFFSETOF (LineTable [Line - 1].LineAddress), /* Source. */ 
LineSelector, /* Target. */ 
LineOffset, /* Target. */ 
LineTable [Line — 1].LineLength - 2); /* Bytes to copy.*/ 

/* Adjust line length for added characters. */ 
LineTable [Line].LineLength += LineTable [Line - 1].LineLength - 2; 

/* Free block used by previous line. */ 
if (WinFreeMem 

(HHeap, /* Handle of heap from 1 WinCreateHeap’. */ 
(BYTE NEAR *)OFFSETOF (LineTable [Line-1].LineAddress), /* Offset. */ 
LineTable [Line-1].LineLength) /* Length of block to free. */ 


! = NULL) 

{ 

sprintf (Message,"managing heap; line %d”,_LINE_); 

ErrorQuit (Message); 

} 


/* Move all ’LineTable’ members above and including ’Line’ down one */ 
/* place. */ 
memmove 

(ScLineTable [Line -1], /* Destination. */ 
&LineTable [Line], /* Source. */ 


(LastLine — Line + 1) * sizeof (LineTable [0])) ; /* Bytes to move.*/ 

—LastLine; 
return TRUE; 

} /* end JoinLine */ 


void NewFile (void) 

/* 

Initializes the file buffer for a new, empty file. 

V 

{ 

PCH FarPtr; /* Temporary far character pointer. */ 

LineBuffer [0] = ’\n’; /* Initialize ’LineBuffer’. */ 

LineBuffer [1] = ’\0’; 
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/* Initialize 'LineTable' for first (and only) line. */ 

LineTable [0].LineAddress = MAKEP (LineSelector, LineOffset); 

LineTable [0].LineLength = 2; 

LastLine = 0; 


/■* Create a heap to hold data added to file. */ 

HHeap = WinCreateHeap 

(0, /* Segment address: 0 means allocate new segment. */ 

4096, /* Initial heap size. */ 

0, /* Minimum increase size: 0 means use default. */ 

0, /* Minimum # of dedicated free lists: none. */ 

0, /* Maximum # of dedicated free lists: none. */ 

HM_MOVEABLE); /* Options: support movable objects. */ 

/* Obtain selector address of heap. */ 

FarPtr = WinLockHeap (HHeap); 

HeapSelector = SELECTOROF (FarPtr); 


} /* end NewFile */ 


int ReadFile /* Reads file into editor. */ 

(char *FileName) /* Name of file. */ 

{ 

FILE *PtrFile; /* File stream pointer. */ 

long FileLength; /* Size of file. */ 

USHORT HeapSize; /* Size of allocated heap. */ 

NPCH HeapOffset; /* Offset of blocks within heap. */ 

unsigned char LineLength; /* Length of lines. */ 

PCH FarPtr; /* Temporary far pointer. */ 

if ((PtrFile = fopen (FileName,"r")) == NULL) /* Open file. */ 

return (ERROPEN); 

/* Get length of file. */ 

if ((FileLength = filelength (fileno (PtrFile))) == -1) 
return (ERROPEN); 

if (FileLength > 50000) /* Test file length. */ 

return (ERRTOOBIG); 

/* Make heap 20% larger than size of file. */ 

HeapSize = (USHORT)(FileLength + FileLength / 5); 

HHeap = WinCreateHeap /* Allocate a heap. */ 

(0, /* Segment address: 0 means allocate new segment. */ 

HeapSize, /* Initial heap size. */ 

0, /* Minimum increase size: 0 means use default. */ 

0, /* Minimum # of dedicated free lists: none. */ 

0, /* Maximum # of dedicated free lists: none. */ 

0); /* Options: none. */ 

FarPtr = WinLockHeap (HHeap); /* Get far address of base of heap. */ 

HeapSelector = SELECTOROF (FarPtr);/* Extract selector value. */ 
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LastLine = -1; /* Initialize index of last line. */ 

while (fgets (LineBuffer,LINEBUFSIZ-1,PtrFile) != NULL) 

{ 

if (-(-+LastLine >= MAXLINES) /* lest limit of number of lines. */ 

return (ERRMAXLINES); 

LineLength = (unsigned char)strlen (LineBuffer) + 1;/* Include null*/ 

if (LineLength == LINEBUFSIZ - 1 6:& /* Insert 1 \n' into */ 

LineBuffer [LINEBUFSIZ - 3] != : 1 \n 1 ) /* overlength lines. */ 

{ 

LineBuffer [LINEBUFSIZ - 2] == > \n • ; 

LineBuffer [LINEBUFSIZ - 1] - •\0'; 

++LineLength; 


HeapOffset = WinAllocMem 
(HHeap, 

LineLength); 

if (HeapOffset == NULL) 
return (ERRALLOC); 


/* Allocate block from heap. 
/* Heap handle. 

/* Length of line to store. 

/* r ?est for error. 


/* Copy line into heap block. 

movedata (LineSelector,LineOffset,HeapSelector, 

(unsigned)HeapOffset,LineLength); 

/* Insert line information into tiie table. 

LineTable [LastLine].LineAddress - MAKEP (HeapSelector,HeapOffset), 
LineTable [LastLine].LineLength = LineLength; 


/* Place line 0 in working buffer. 
GetTempBuf (0); 

fclose (PtrFile); 
return (0); 


/* 21ose the file. 


/* end of ReadFile */ 


void ReleaseFile (void) 


Destroys the current heap, thereby freeing all file data. 


if (HHeap 1= NULL) 

WinDestroyHeap (HHeap); 


} /* end ReleaseFile */ 
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void 

ReleaseTempBuf 



/* 

(int Line) /* Number of line held in 1 LineBuffer'. 

V 

This function: 

o Allocates a new block of memory 

just large enough to hold the string 

in 



the 'LineBuffer' 




o Copies the string into the new block 


*/ 

o Adjusts the address in 'LineTable' 



( 

NPC.’H HeapOffset; 

/* Offset of block within heap. 

*/ 


/* Allocate a block to hold current contents of 'LineBuffer'. 

V 


HeapOffset = WinAllocMem 




(HHeap, 

LineTable [Line].LineLength); 




if (HeapOffset == NULL) 




i 

sprintf (Message,"out of heap 
ErrorQuit (Message); 

} 

memory; line %d",_LINE_); 



/* Copy characters from 'LineBuffer' into new block in heap. 

*/ 


movedata 

/* Intersegment block copy. 

*/ 


(LineSelector, 

/* Source: selector of line buffer. 

V 


LineOffset, 

/* Source: offset of line buffer. 

V 


HeapSelector, 

/* Target: selector of heap. 

*/ 


(unsigned)HeapOffset, 

/* Target: offset of new block. 

V 


LineTable [Line].LineLength) ; 

/* Bytes to copy. 

*/ 


/* Adjust address in 'LineTable' to point to new block. 

LineTable [Line].LineAddress = MAKEP (HeapSelector, HeapOffset); 

V 


} /* end ReleaseTempBuf */ 



int 

SaveFile (char *FileName) 




X 

register int i; 

/* Loop counter. 

*/ 


FILE *PtrFile; 

/* File stream pointer. 

*/ 


char TempBuffer [LINEBUFSIZ]; 

/* Temporary local buffer for lines. 

*/ 


PCH FarPtr; 

/* Temporary far pointer. 

*/ 


unsigned BufSel; 

/* Selector of 'TempBuf'. 

*/ 


if ((PtrFile = fopen (FileName,"w" 

)) == NULL) /* Open file. 

*/ 


return FALSE; 




FarPtr = (char far *)TempBuffer; 
BufSel = SELECTOROF (FarPtr); 

/* Obtain selector for 'TempBuf'. 

V 


/* Write file line by line, 
for (i = 0; i <= LastLine; ++i) 


V 


i 

/* First copy line into a local buffer. 

*/ 


movedata 

/* Block copy. 

*/ 
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(SELECTOROF (LineTable [i].LineAddress), /* Source selector. */ 
OFFSETOF (LineTable [i].LineAddress), /* Source offset. */ 
BufSel, /* Target selector. */ 
(unsigned int) TempBuffer, /* Target offset. */ 
LineTable [i].LineLength); /* Length of line. */ 

/* Write line to file. */ 
fputs (TempBuffer, PtrFile); /* Write a line to file. */ 
} 

fclose (PtrFile); /* Close file. */ 


return TRUE; 

} /* end SaveFile */ 


int 

/* 


*/ 


SearchBuf (char *FindString, PSHORT Line, PSHORT Col) 


Searches file buffer 
'Line 1 and ’Column', 
position immediately 
string is not found, 
returns FALSE. 


for string 'Findstring 1 , from position given by 
If string is found, updates ’Line' and ’Col’ to 
after the string in buffer, and returns TRUE. If 
function does not update 'Line' and 'Col', and it 


{ 

register int i, j; 
char far *FPtrCh; 


FPtrCh = LineTable [*Line].LineAddress + *Col; 
i = *Line; 
for (;;) 


while (*FPtrCh) 

{ 

for (j = 0; FindString [j] === FPtrCh [j] && FindString [j]; ++j) 

if (FindString [j] == '\0' ) 

( 

*Line = i; 

*Col = FPtrCh + j - LineTable [i].LineAddress; 
return TRUE; 

) 

++FPtrCh; 

} 

if (++i > LastLine) 
return FALSE; 

FPtrCh = LineTable [i].LineAddress; 

) 

} /* end SearchBuf */ 
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void ErrorQuit /* Terminate program due to fatal error condition. */ 


(char ^Message) /* Error message to display to user. */ 

{ 

char Buffer [60]; 

sprintf (Buffer, "Program Error: %s",Message); 

WinMessageBox /* Display a message box. _ */ 

(HWND DESKTOP, /* Handle of parent: desktop window. */ 

HFrame, /* Handle of owner: frame window. */ 

Buffer, /* Message text. */ 

"PM Text Editor", /* Caption. */ 

0 , /* Help window ID: not needed. */ 

MB OK | /* Display an 'OK' button. */ 

MB~ICONHAND); /* Display a hand icon. */ 

Quit (1); /* Call normal termination function. */ 

} /* end ErrorQuit */ 


char ^Extension (char *FileName) 

/* 

Returns a pointer to the beginning of the extension contained m 
’FileName', or NULL if there is no extension. 

*/ 

{ 

while (*FileName) 

if (*FileName++ == '.') 
return (FileName); 
return (FileName); 

} /* end Extension */ 

void GetPath (char *Path, unsigned PathSize) 

/* 

Copies fully qualified path to 'Path'; will not copy beyond the length of 
'Path' given by PathSize. 

*/ 


USHORT DriveNumber; /* Disk drive number. */ 

ULONG LogicalDrives; /* Mapping of installed drives. */ 

/* if target buffer is too small, return without altering it. */ 

if (PathSize < 3) 
return; 

/* obtain current default disk and mapping of installed drives. */ 

DosQCurDisk 

(StDriveNumber, /* Receives number of current drive. */ 

&LogicalDrives)? /* Receives mapping of installed drives. */ 

/* Write drive letter to ’Path'. */ 


• Figure 8.38: 
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sprintf (Path,"%c:\\",DriveNumber + 64j ; 


/* Adjust 'PathSize' for drive specification. */ 

PathSize -= 3; 

/* Obtain current default directory. */ 

DosQCurDir 

(DriveNumber, /* Drive number: current drive. */ 

Path +3, /* Address of buffer to receive directory. */ 

&(USHORT)PathSize); /* Length of buffer to receive directory. */ 


return; 

} /* end GetPath */ 


void InitWindow (void) 

/* 

This function initializes the window when a new file is read ('Open' 
file menu item), or when a new empty file is started (’New' file menu 
item). It performs the following tasks: 

o Initializes global cursor and window variables so that the cursor 
is placed at the first character of the file, and the beginning of 
the file is displayed in the window, 
o Adjusts range and position of horizontal and vertical scroll bars, 
o Positions the cursor at top left of window. 

o Invalidates the entire window to force displaying the new data. 

*/ 

{ 

Cursored = CursorLine = 0; 

TopLine = FirstCol = 0; 

TopLineMax = max (0,LastLine - yWin / yCharTot + 1); 

FirstColMax = LINEBUFSIZ - 2 - xWin / xChar; 


WinSendMsg /* Adjust range/position of slider. */ 

(HVScroll, /* Recipient handle: vertical scroll bar. */ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (TopLine, 0), /* Position. */ 

MPFROM2SHORT (0, TopLineMax)); /* Range. */ 

WinEnableWindow /* Enable scroll bar if scrolling is possible. */ 

(HVScroll, /* Recipient handle (vertical scroll bar).*/ 

TopLineMax ? TRUE : FALSE); /* Enable only if max. != 0. */ 

WinSendMsg /* Adjust range/position of slider. */ 

(HHScroll, /* Recipient handle: horizontal scroll bar*/ 

SBM_SETSCROLLBAR, /* Set position & range. */ 

MPFR0M2SHORT (FirstCol, 0), /* Position. */ 

MPFR0M2SHORT (0, FirstColMax)); /* Range. */ 

if (HClient == WinQueryFocus (HWND_DE3KT0P,FALSE)) 

WinCreateCursor /* Set cursor position. */ 

(HClient, 

(Cursored - FirstCol) * xChar, 

yWin - (CursorLine - TopLine + 1) * yCharTot, 

0 , 
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0 , 

CURSOR_SETPOS, 

NULL) ; 

/* Invalidate entire window. 

/* Client window handle. 

/* Rectangles 0 means whole window. 

/* Do not automatically include children. 

} /* end InitWindow */ 


WinlnvalidateRect 

(HClient, 

0 ,, 

FALSE) ? 


V 
*/ 
*/ 

V 


void Qualify (char *Unqual, char *Qual) 

/* 

Converts file name 'Unqual' (either a simple or qualified file name) to 
a fully qualified file name, which includes the drive specification and 
full directory path, and is copied to 'Qual'. 

V 

( 

char PathBuffer [PATHLENGTH]; 
char *PtrPath = PathBuffer; 

GetPath (PathBuffer, sizeof (PathBuffer))? 

if (*(Unqual + 1) == ' :') 

{ 

*Qual++ = *Unqual++; 

*Qual++ = *Unqual++; 

PtrPath += 2; 

} 

else 

{ 

*Qual++ = *PtrPath++; 

*Qual++ = *PtrPath++; 

} 

if (*Unqual != *\\*) 

{ 

while (*Qual++ = *PtrPath++) 

if (*(Qual - 2) == *\\') 

—Qual; 

else 

* (Qual - 1) = 'W; 

} 


while (*Qual++ = *Unqual++) 


} /* end Qualify */ 


void Quit (int ErrorCode) 

/* 

Calls Presentation Manager termination functions and ends program 
with termination status given by 'ErrorCode’. 
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V 

{ 

USHORT Reply; /* Response from message box. */ 

/*** if buffer is modified, query user whether to save file. *****************/ 
if (Modified) 

{ 

Reply = WinMessageBox 
(HWND_DESKTOP, 

HClient, 

"File Unsaved; Save?", 

"PM Text Editor", 

0, 

MB_YESNO | 

MB_ICONQUESTION); 

/* If reply is Yes, send a ‘Save 1 menu message to client, 
if (Reply == MBID_YES) 
while (Modified) 

WinSendMsg 

(HClient, /* Client window handle. 

WM_COMMAND, /* Menu message. 

MPFR0M2SHORT (ID_SAVE, 0),/* Command for ’Save' 

0L); /* mp2 : not used. 

} 

if (HHeap != NULL) 

WinDestroyHeap (HHeap); 

WinDestroyWindow (HFrame); 

WinDestroyMsgQueue (HMesQue); 

WinTerminate (HAncBlk); 
exit (ErrorCode); 

} /* end Quit */ 


void ShowFileName (void) 

/* 

Updates the text in the title bar to show the current file name. 

V 

{ 

/* Format title. */ 

sprintf (Title, "PM Editor - %s", FileName[0] ? Unqualify (FileName) 

: "(Untitled)"); 

/* Modify the title bar window text. */ 

WinSetWindowText 

(HFrame, /* Window handle: frame routes text to menu. */ 

Title); /* String containing the text. */ 

} /* end ShowFileName */ 


char *Unqualify (char *Qual) 
/* 


*/ 

*/ 

item*/ 

*/ 
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Returns a pointer to the simple file name within the string 'Qual', 
which contains a partially or fully specified file path. Converts the 
unqualified file name to uppercase. 

{ 

char *PtrCh; 

PtrCh = Qual + strlen (Qual); 

while (PtrCh != Qual && 

*(PtrCh-1) != '\\* && 

*(PtrCh-1) I= ':') 

—PtrCh; 

WinUpper 

(HAncBlk, 

NULL, 

NULL, 

PtrCh) ; 

return (PtrCh) ; 

} /* end Unqualify */ 

• Figure 8.38: 
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/* Convert unqualified name to uppercase. */ 


/* Anchor block handle. */ 
/* Code page: use current. */ 
/* Country code: use default. */ 
/* Address of string to be converted. */ 









■ 
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he clipboard is a Presentation Manager facility for trans¬ 
ferring data. Once an application has placed a block of 
data into the clipboard, the data can be accessed by the 
same application, or by any other program running 
within a Presentation Manager window. The clipboard thus provides a 
single, convenient mechanism for moving blocks of data within a pro¬ 
gram, and for effecting data exchange among separate applications. 

In this chapter you will learn how to place data into the clipboard, 
and how to access data contained in the clipboard; you will learn how 


to use the clipboard to implement commands for cutting, copying, and 
pasting data within a single program or among separate applications; 
and you will learn how to add a clipboard interface to the example pro¬ 
gram developed in the first part of the book. The chapter focuses on the 
basic methods for exchanging data in a standard text format; the last 
section, however, introduces some of the advanced features of the 
Presentation Manager clipboard, and includes a discussion of alterna¬ 
tive data formats. 


. ADDING DATA TO THE CLIPBOARD 

An application can place a block of data into the clipboard at any 
time. Normally, however, data are inserted into the clipboard in 
response to a command issued by the user. Presentation Manager 
programs typically provide commands for selecting a block of data, and 
then copying or cutting (that is, removing) this data selection and ad¬ 
ding it to the clipboard. The section on Implementing a Clipboard Inter¬ 
face, later in the chapter, discusses the menu commands that initiate 
these operations and the techniques for marking a data selection. This 
section assumes that a block of data is already available and describes 
the procedure for actually inserting this block into the clipboard. 

Note that the clipboard is a global Presentation Manager resource, 
available to any program running within a Presentation Manager win¬ 
dow. Since the data your program places into the clipboard may be 
removed by another application, you must designate the data format so 
that an arbitrary receiving application can determine whether it can 
process the data. Note also that the clipboard can hold only a single 
data selection at a given time; therefore, when your program adds a 
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block of data, the previous clipboard contents are destroyed. (More ac¬ 
curately, the clipboard can contain only a single block of data in a given 
format; the clipboard can hold several blocks of data, as long as each 
block has a distinct format. This feature allows an application to insert 
the same data selection in several different formats so that the data can 
be used by a greater variety of receiving applications.) This section 
describes the methods for adding blocks of data that conform to the 
standard text format. 

The following are the five basic steps that an application must perform 
to add a block of textual data to the Presentation Manager clipboard: 

1. Allocate a sharable memory segment. 

2. Copy the data into this segment. 

3. Open the clipboard. 

4. Add the data segment to the clipboard. 

5. Close the clipboard. 


Allocate a Memory Segment 

The Presentation Manager clipboard facility does not provide the 
actual memory for holding the data that are placed into the clipboard; 
rather, it maintains only the addresses of the blocks of data. Your pro¬ 
gram must explicitly allocate a memory segment from the operating 
system to hold any block of data that it submits to the clipboard. Fur¬ 
thermore, since this data segment may be accessed by another process, 
the memory segment must be designated as sharable. 

To allocate a shared memory segment suitable for holding a block of 
clipboard data, you can call the OS/2 kernel function DosAllocSeg. 
This function is explained in Figure 9.1, and should be called as in the 
following example: 

USHORT SelectionSize; 

SEL SelClipData; 
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DosAllocSeg 

(SelectionSize, 

&SelClipData, 

SEG_GETTABLE) ; 

The first parameter in this example specifies the length of the segment 
in bytes. You should request a segment large enough to hold the data 
selection that is to be inserted into the clipboard (in this example, the 
variable SelectionSize has presumably been assigned the number of 
bytes in the current data selection). The second parameter supplies the 
address of the variable that is to receive the segment selector. The final 
parameter passes the flag SEG_GETTABLE, which specifies that the 
segment is to be shared through the OosGetSeg OS/2 function, which 
will be explained in the section on Accessing Data in the Clipboard, 
later in the chapter. 

Note that your application does not have to free the segment contain¬ 
ing the clipboard data. Rather, the Presentation Manager automatically 
frees this segment (by calling DosFreeSeg) when the clipboard data are 
replaced through a subsequent data submission or are explicitly cleared 
by means of the WinEmptyClipbrd Presentation Manager function 
(Figure 9.6, discussed later in the chapter). 

Note also that when allocating a segment for the clipboard, you 
should call DosAllocSeg rather than OosAllocShrSeg. Both of these 
functions can be used to obtain shared memory segments. DosAlloc- 
ShrSeg, however, provides a named shared memory segment, which 
another process cannot access unless it knows the segment name. Dos¬ 
AllocSeg, on the other hand, provides what is termed a giveaway shared 
memory segment; the Presentation Manager clipboard can grant access 
to this type of segment to another process by simply passing it the seg¬ 
ment selector. (See the section on Accessing Data in the Clipboard for 
details on how the second process obtains segment access once it has 
received the selector.) 


Copy the Data 

Once you have allocated a segment to hold the clipboard data, the 
next task is to copy the selected data into this segment. As you copy 
the data selection into the sharable segment, you may have to modify it 
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DosAllocSeg 

Purpose: 

Allocates a memory segment. 

Prototype: 

USHORT APIENTRY DosAllocSeg 

(USHORT usSize , The size of the segment in bytes (from 

0 to 65,535; the value 0 allocates a 
65,536-byte segment). 

psel psei, Address of the variable to receive the 

segment selector. 

ushort fAlloc) ; The allocation flags, which can be a 

combination of one or more of the 
following values: 

Value Effect 

0 Creates a nonsharable, 

nondiscardable segment 

SEG_GIVEABLE Calling process can call 

DosGiveSeg to obtain 
a selector that can be 
used by another 
process to access the 
segment 

SEG_GETABLE Another process can 

obtain access to the 
segment by passing the 
selector (psel) to the 
DosGetSeg function 

SEG DISCARDABLE Creates a discardable 
segment 

® Figure 9.1: 

The DosAllocSeg OS/2 kernel function 
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Return Value: 

Returns 0 if the function is successful, or the value 
ERROR_NOT_ENOUGH_MEMORY if insufficient memory 
is available to fill the allocation request. 

Notes: 

The segment can be freed by calling the DosFreeSeg function. 

Related Functions: 

DosFreeSeg (Figure 10.27) 

DosGetSeg (Figure 9.7) 


» Figure 9.1: 

The DosAllocSeg OS/2 kernel function (continued) 

to conform to the specified data format. (The format is specified when 
the segment is submitted to the clipboard; this process is described later 
in the chapter.) If the data selection conforms to the standard text for¬ 
mat, it should be copied into the sharable segment observing the fol¬ 
lowing conventions: 

» Each line should end with a carriage-return ('\r') and linefeed 
('\n') combination. Note that C programs typically use only the 
'\n' character to terminate individual lines within textual data; 
you may therefore have to insert accompanying '\r' characters 
as the data are copied into the sharable segment. 

• The tab character ('\t') can be used to separate data fields within 
a single line. 

@ The entire data block is terminated with a single NULL character 
('\ 00 . 

According to these conventions, the data block consists of a single 
NULL-terminated string, which may contain one or more lines of text. 
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As an example, the following code copies a block of data into a memory 
segment allocated for the clipboard: 


char far *PtrSelection; 
SEL SelClipData; 
unsigned int DataLength; 


movedata 


(SELECTOROF (PtrSelection), 

/* 

Source 

selector. 

*/ 

OFFSETOF (PtrSelection), 

/* 

Source 

offset. 

*/ 

SelClipData, 

/* 

Target 

selector. 

*/ 

o, 

/* 

Target 

offset. 

*/ 

DataLength); 

/* 

Bytes to copy. 

*/ 


This example uses the C library function movedata, which copies data 
from one segment to another. Note that it does not perform data trans¬ 
lation; it assumes that the data are already in the proper format. This ex¬ 
ample also assumes that PtrSelection has been assigned the far address 
of the data selection within the program, that SelClipData contains the 
selector of the sharable segment supplied by DosAllocSeg, and that 
DataLength has been assigned the number of bytes contained in the 
data selection that is to be copied into the sharable segment. 


Open the Clipboard 

Before an application can access the clipboard (either to add or to 
obtain a data block), it must call the Presentation Manager function 
WinOpenClipbrd (Figure 9.2) to open the clipboard for the current pro¬ 
gram thread. The purpose of this function is to grant the program ex¬ 
clusive access to the clipboard data, thereby preventing conflicts among 
separate applications that are using the clipboard. Once your applica¬ 
tion has opened the clipboard through WinOpenClipbrd, no other pro¬ 
gram may open it until your application calls WinCloseClipbrd 
(explained later) to close the clipboard. If another program calls Win¬ 
OpenClipbrd after your application has opened the clipboard, this 
function does not return until your application has closed the clipboard. 
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Therefore, holding an open clipboard may block other programs; ac¬ 
cordingly, you should close the clipboard as soon as possible (for ex¬ 
ample, allocate the sharable segment and copy the data into this 
segment before opening the clipboard). 

The following example illustrates the use of WinOpenClipbrd: 

HAB HAncBlk; 


WinOpenClipbrd 

(HAncBlk); /* Anchor block handle. */ 


WinOpenClipbrd 

Purpose: 

Opens the clipboard for the current thread, to provide this 
thread exclusive access to the clipboard. 

Prototype: 

BOOL APIENTRY WinOpenClipbrd 
(hab hab) ; Anchor block handle. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

If another thread already has the clipboard open, this func¬ 
tion does not return until this thread has closed the clip¬ 
board. The clipboard is closed by calling WinCloseClipbrd. 

Related Functions: 

WinCloseClipbrd (Figure 9.4) 


® Figure 9.2: 

The WinOpenClipbrd Presentation Manager function 
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The value HAncBlk, passed as the parameter to WinOpenClipbrd, is 
the anchor block handle returned by the call to Winlnitialize (Figure 
2.2) issued at the beginning of the Presentation Manager application. 


Insert the Data 
Segment into the Clipboard 

Once you have opened the clipboard, you can place the sharable 
segment within the clipboard by calling the WinSetClipbrdData 
Presentation Manager function (Figure 9.3). When you add a block of 
data to the clipboard with this function, you must specify the data for¬ 
mat; these data replace any block of data having the same format that is 
already in the clipboard. When adding a block of standard textual data 
to the clipboard, you should call WinSetClipbrdData, as in the follow¬ 
ing example: 

HAB HAncBlk; 

SEL SelClipData; 


WinSetClipbrdData 

(HAncBlk, 

(ULONG)MAKEP (SelClipData, 0) , 
CF_TEXT, 

0 ) ; 


The first parameter passed to this function is the anchor block handle 
returned by the call to Winlnitialize. The expression passed as the 
second parameter generates a far pointer to the base of the sharable seg¬ 
ment that was allocated through DosAllocSeg. (DosAllocSeg assigns 
the segment selector to SelClipData, which is combined here with a 0 
offset.) The third parameter specifies the data format; the value 
CF_TEXT indicates the standard text format that was described earlier 
in the chapter (in the section entitled Copy the Data). Note that the data 
format is stored in the clipboard along with the data address; as you 
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WinSetClipbrdData 
Purpose: 

Places a block of data into the clipboard. 
Prototype: 

BOOL APIENTRY 
(HAB hab, 

ULONG ulData, 


USHORT fmt, 


Identifier Format 

CF_TEXT Standard text format 

CFJBITMAP Bitmap format 

CF_METAFILE Metafile format 

CF_DSPTEXT Text display format 

associated with a 
private format 

CFJDSPBITMAP Bitmap display format 
associated with a 
private format 


WinSetClipbrdData 

Anchor block handle. 

Handle to the block of data to be 
inserted into the clipboard. If the data 
is formatted as text, this parameter 
supplies the far address of the base of 
the sharable segment containing the 
data; if the data is a bitmap or metafile, 
this parameter contains the handle to 
the object. Passing a value of NULL 
indicates that the clipboard owner will 
delay rendering the data until it 
receives a WM_RENDERFMT message 
Format of the data; you can specify a 
private format or one of the following 
predefined formats: 


® Figure 9.3: 

The WinSetClipbrdData Presentation Manager function 
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ushort rgfFmtinf o) ; Information on the data block referenced 
by the parameter ulData. You can 
specify a memory model and a usage 
flag from the following values (you can 
select 0 or 1 memory model, and 0,1, or 
2 usage models; values are combined 
with the bitwise OR operator): 


Memory Model Meaning 

CFI_SELECTOR The parameter ulData 

contains a segment 
selector combined with 
a 0 offset 

CFI_HANDLE The parameter ulData 

is the handle of a 
bitmap or a metafile 


Usage Flag Meaning 

CFI_OWNERFREE The handle is not 

automatically freed by 
the system; the 
clipboard owner must 
explicitly free the 
handle in response to 
the WM_DESTROY- 
CLIPBOARD message 

CFI OWNER- The clipboard owner 

DISPLAY will display the 

contents of the 
clipboard within the 
viewer window in 
response to the 
WM_PAINT CLIPBOARD 
message (ulData 
should be NULL) 


Figure 9.3: 

The WinSetClipbrdData Presentation Manager function (continued) 
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Return Value: 

TRUE if the data was placed into the clipboard, or FALSE if 
the data was not added to the clipboard (either because of an 
error, or because the handle ulData was NULL). 

Notes: 

If you specify a predefined data format (text, bitmap, or 
metafile), you do not need to assign a memory model 
through the rgfFmtlnfo parameter. 

Related Functions: 

WinQueryClipbrdData (Figure 9.5) 


• Figure 9.3: 

The WinSetClipbrdData Presentation Manager function (continued) 

will see, when a program accesses data within the clipboard, it must re¬ 
quest a specific data format. (Formats other than text are listed in the 
last section of the chapter.) 

The last parameter supplies additional information concerning the 
block of data specified by the second parameter. When submitting data 
in the standard text format, you do not need to specify any of the values 
that may be passed through this parameter. (Some of the possible 
values for this parameter listed in Figure 9.3 are described in the last 
section of the chapter.) 

Note that once your program has called WinSetClipbrdData to sub¬ 
mit the address of the shared data segment to the system, it should no 
longer use this address. Rather, if your program requires subsequent access 
to the block of data, it should follow the standard procedures for accessing 
data within the clipboard, described later in the chapter. (Data belonging to 
the clipboard must be accessed through the system so that at a given time 
only one program thread can add, read, or remove data. Also, the system 
may have freed the original segment selector passed to WinSetClipbrd¬ 
Data; using such a selector will generate a protection fault.) 
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Close the Clipboard 

After the data segment has been placed in the clipboard, the pro¬ 
gram should call WinCloseClipbrd (Figure 9.4) to relinquish its ex¬ 
clusive access to the clipboard. As mentioned previously, you should 
call this function as soon as possible to minimize the amount of time 
any other applications attempting to open the clipboard are blocked. 


WinCloseClipbrd 

Purpose: 

Closes the clipboard, previously opened through WinOpen- 
Clipbrd. 

Prototype: 

BOOL APIENTRY WinCloseClipbrd 

(hab hab) / Anchor block handle. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

By calling this function, an application relinquishes its ex¬ 
clusive access to the clipboard, and other applications are 
free to open the clipboard. 

Related Functions: 

WinOpenClipbrd (Figure 9.2) 


• Figure 9.4: 

The WinCloseClipbrd Presentation Manager function 
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The following is an example of a call to the WinCloseClipbrd function: 

HAB HAncBlk; 


WinCloseClipbrd 
(HAncBlk) ; 


ACCESSING DATA 
. IN THE CLIPBOARD 

This section describes the techniques for obtaining a block of data 
from the clipboard. A program typically requests data from the clipboard 
in response to a paste command issued by the user (that is, a command to 
copy a block of data from the clipboard and insert it into the data main¬ 
tained by the program). When requesting a block of data, your program 
must specify a particular format; if the clipboard contains a block that con¬ 
forms to this format, it will supply the data handle (in the case of textual 
data, the handle is the far address of the segment holding the data). The 
block that the system provides is the one with the requisite format that has 
most recently been added to the clipboard (remember that the clipboard 
maintains only a single block in a given format). This block may have been 
placed in the clipboard by your program, or by another Presentation 
Manager application. This section describes the methods for accessing 
blocks of data that conform to the standard text format. 

Note that obtaining a block of data from the clipboard merely allows 
your program to read or copy this block; it does not remove it from the 
clipboard. Therefore, the same block can be repeatedly accessed. (The 
block is not removed until another block with the same format is added, 
or a program calls WinEmptyClipbrd, described later in Figure 9.6.) 

The following five steps can be used to access a block of textual data 
contained in the clipboard: 

1. Open the clipboard. 

2. Obtain the address of the block. 
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3. Secure access to the shared memory segment. 

4. Process or copy the block. 

5. Close the clipboard. 


Open the Clipboard 

Your program must call WinOpenClipbrd (Figure 9.2) to open the 
clipboard before accessing a data block, just as it must open the clip¬ 
board prior to adding a block. This function was described in the sec¬ 
tion on Adding Data to the Clipboard, and it is called as follows: 

HAB HAncBlk; 


WinOpenClipbrd 

(HAncBlk); /* Anchor block handle. */ 


Obtain the Address of the Block 

To obtain access to a block of data in the clipboard, you should call 
the WinQueryClipbrdOata Presentation Manager function (Figure 9.5), 
specifying the desired data format. If the clipboard currently contains a 
block with the requested format, WinQueryClipbrdOata returns a 
handle to this data; if the clipboard does not contain such a block, the 
function returns NULL. If the data is in the text format, the handle con¬ 
sists of the far pointer (that is, the selector and offset) of the segment 
containing the data. 

The following call to WinQueryClipbrdOata requests a data block in 
text format: 

PCH PtrData; 

HAB HAncBlk; 
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PtrData = (PCH) WinQueryClipbrdData 
(HAncBlk, 

CF_TEXT); 

if (PtrData != NULL) 

/* then you can process the data... */ 

As mentioned previously, calling WinQueryClipbrdData merely al¬ 
lows your program to read or copy the data block, but does not remove 
the block from the clipboard. If you want to eliminate a block from the 
clipboard, you should call the Presentation Manager function Win- 
EmptyCiipbrd, described in Figure 9.6. 


WinQueryClipbrdData 

Purpose: 

Returns a handle to the block of data in the clipboard that 
has the requested format. 

Prototype: 

ULONG APIENTRY WinQueryClipbrdData 

(hab hab, Anchor block handle. 

ushort fmt ) ; Desired data format (see Figure 9.3 for a list 

of the predefined formats). 

Return Value: 

Handle to the data block having the requested format, or 
NULL if the clipboard does not contain a block with this for¬ 
mat or if an error occurred. If the block is in text format, the 
handle is the far address of the memory segment containing 
the data. 

Related Functions: 

WinSetClipbrdOata (Figure 9.3) 


• Figure 9.5: 

The WinQueryClipbrdData Presentation Manager function 
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WinEmptyClipbrd 

Purpose: 

Removes all data blocks from the clipboard, freeing the as¬ 
sociated data handles. 

Prototype: 

BOOL APIENTRY WinEmptyClipbrd 

(hab hab) / Anchor block handle. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 


• Figure 9.6: 

The WinEmptyClipbrd Presentation Manager function 


Secure Access 

to the Shared Memory Segment 

If the handle returned by WinQueryClipbrdData is not NULL, 
the next step is to call DosGetSeg (Figure 9.7) to secure access for the 
current process to the segment containing the clipboard data. Although 
WinQueryClipbrdData returns a far pointer to this segment, this ad¬ 
dress may have been supplied by another process (which would be the 
case if the data in the clipboard were inserted by another application). 
Even though the other process may have allocated the memory block as 
a sharable segment (by passing DosAllocSeg the SEG_GETABLE flag), 
the selector portion of this address is not automatically valid within the 
current process. Before using this selection, your program must call 
DosGetSeg to make the selector valid within the current process. 

The following is an example of a call to DosGetSeg: 


PCH PtrData; 
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DosGetSeg 

(SELECTOROF(PtrData)); 

This example assumes that PtrData contains the far pointer to the clip¬ 
board data returned by WinQueryClipbrdData; note that only the 
selector portion is passed to DosGetSeg. After calling this function, the 
program may safely use PtrData to access the clipboard data. 


DosGetSeg 

Purpose: 

•Secures access to a shared memory segment for the current 
process. 

Prototype: 

USHORT APIENTRY DosGetSeg 

(SEL sel) ; The selector of the shared memory segment. 

Return Value: 

Zero if the function was successful, or a nonzero error code if 
the function failed. 

Notes: 

A selector to a shared memory segment obtained from Dos- 
AllocSeg can be passed to a second process. The second 
process, however, must call DosGetSeg before it can use this 
selector. The call to DosAllocSeg must have included the 
SEG_GETABLE allocation flag in the third parameter. 

Related Functions: 

DosAllocSeg (Figure 9.1) 

• Figure 9.7: 

The DosGetSeg OS/2 kernel function 
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A technical note: The selector that a process obtains from DosAllocSeg 
is the index of a segment descriptor within the process's local descriptor 
table. Since each process owns a distinct local descriptor table, this 
selector is initially valid only within the process that called DosAlloc¬ 
Seg. When a second process passes the selector to DosGetSeg, how¬ 
ever, the system places a new descriptor in the local descriptor table 
belonging to the second process. This new descriptor is indexed by the 
same selector, and it describes the same memory segment as the de¬ 
scriptor belonging to the first process. Therefore, after calling DosGet¬ 
Seg, the second process can use the selector to access the shared 
segment. See the section in Chapter 1 on Virtual Memory. 


Process or Copy the Block 

Once your application holds a valid selector to the clipboard data, 
it should process these data quickly and then close the clipboard. If the 
application needs to retain the data, it should copy the block into a local 
buffer, where it can perform the required processing at its leisure. Rapid 
processing is important because, as explained previously, the clipboard 
should be closed as soon as possible. Once the clipboard is closed, how¬ 
ever, the application cannot use the segment selector obtained from the 
clipboard; the sharable clipboard segment is therefore available for a 
limited amount of time. 

An application such as the text editor presented in the first part of 
this book should copy the clipboard data directly into the buffer hold¬ 
ing the file data; it should then close the clipboard before updating the 
window display. 


Close the Clipboard 

After your application has finished processing or copying the clip¬ 
board data, it should call WinCloseClipbrd (Figure 9.4) to relinquish its 
exclusive access to the clipboard. After calling WinCloseClipbrd, the 
program must not attempt to use the selector obtained from WinQuery- 
ClipbrdData to access the clipboard data. (Remember that a similar 
restriction was imposed when adding data to the clipboard.) 
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IMPLEMENTING 
• A CLIPBOARD INTERFACE 

The first sections in this chapter have described the basic Presenta¬ 
tion Manager facilities that allow a program to insert a data selection 
into the clipboard or to obtain the data selection that is currently con¬ 
tained in the clipboard. This section describes a typical program inter¬ 
face that permits the user to access these underlying facilities, and offers 
suggestions for using the clipboard within the text editor example pro¬ 
gram that was presented in the first part of the book. The user interface 
described in this section follows the recommended style guidelines (as 
described in the Microsoft Windows Application Style Guide, cited in the 
Bibliography). Note that this section focuses on the techniques for 
selecting and exchanging textual data (as opposed to graphical data; the 
last section in this chapter briefly discusses nontext formats). 

In a Presentation Manager application such as a text editor, there is a 
one-to-one correspondence between the block of data contained in the 
clipboard and the current program selection. The selection is a section of 
data chosen by the user and typically highlighted within the window 
display; at a given time, there may or may not be a selected block of 
data. When the user requests a cut clipboard operation, the selected 
data are copied to the clipboard and removed from the program. A copy 
operation copies the selected data into the clipboard but leaves the data 
within the program. A paste command copies the contents of the clip¬ 
board into the program data; if a block of program data is currently 
selected, the block of data copied from the clipboard typically replaces 
the program selection. Finally, a clear operation deletes the selection 
from the program but does not add the data to the clipboard. Concep¬ 
tually, the clipboard stores a single program selection (although it can 
actually maintain several blocks of data that have distinct formats). 

Accordingly, the first step in implementing a clipboard interface is to 
provide a mechanism for selecting a block of data and for highlighting 
the selection within the window display In a program such as a text 
editor, the user should be able to make a data selection using either the 
keyboard or the mouse. The recommended keystroke for extending a 
selection is the Shift key in combination with one of the four arrow 
keys; with the Shift key held down, an arrow key extends the selection 
in the corresponding direction. You can process these keystrokes in the 
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routine that handles WM_CHAR messages. As the selection is ex¬ 
tended, its dimensions should be maintained in global variables that 
can subsequently be accessed by the routine that highlights the selected 
text in the window display and by the routine that executes the clip¬ 
board operations. The mouse interface for marking a selection is 
described in Chapter 11. Note that in addition to allowing the user to 
extend the selection character-by-character in any direction, a full-fea¬ 
tured text editor or word processor should provide keyboard and 
mouse commands for selecting entire words or lines. 

For each keystroke that alters the current selection, the window pro¬ 
cedure should execute a routine to update the highlighted area that 
marks the current selection within the window. This routine can alter 
the highlighting of a block of characters on the screen (either highlight¬ 
ing the characters or removing the highlighting) by setting the back¬ 
ground and foreground colors and then redrawing the characters using 
the GpiCharStringAt function (Figure 3.28). The following list sum¬ 
marizes the basic steps: 

• Obtain a presentation space by calling WinGetPS (Figure 3.19). 

• Set the current character font as described in Chapter 3. 

• Hide the cursor by calling WinShowCursor (Figure 5.5), passing 
a value of FALSE as the second parameter. 

• Call the function GpiSetBackMix (Figure 9.8), passing the value 
BM_OVERPAINT as the second parameter to force GpiChar¬ 
StringAt to overwrite the current background color. 

• Set the background color to black by calling GpiSetBackColor 
(Figure 9.9), passing the value CLR_BLACK as the second 
parameter (or set it to white by passing CLR_WHITE to remove 
the highlighting and restore the normal character colors). 

• Set the foreground color to white by calling GpiSetColor (Figure 
3.29), passing the value CLR_WHITE as the second parameter 
(or set it to black by passing CLR_BLACK to remove the high¬ 
lighting and restore the normal character colors). 

• Use the function GpiCharStringAt to reprint the selected charac¬ 
ters using the newly designated colors. 


GpiSetBackMix 


Purpose: 

Specifies the way the background color generated by 
graphics functions (such as GpiCharStringAt) is combined 
with the existing color within the presentation space. 


GpiSetBackMix 

Handle to the presentation space. 

The mode, which can be one of the following 
values: 


Value 

Effect 

BM_DEFAULT 

The default value 
(same as 

BM_LEAVEALONE) 

BM_OR 

The pixel colors are 
combined using the OR 
operator 

BM_OVERPAINT 

The object background 
color replaces the 
existing color 

BM_XOR 

The pixel colors are 
combined using the 
exclusive-OR operator 

BM LEAVE- 

The existing color in 

ALONE 

the background areas is 
left unaltered (the 
default) 


Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Related Functions: 

GpiCharStringAt (Figure 3.28) 

GpiSetBackColor (Figure 9.9) 

• Figure 9.8: 

The GpiSetBackMix Presentation Manager function 


Prototype: 

BOOL APIENTRY 
(HPS hps, 

LONG IMixMode); 
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GpiSetBackColor 

Purpose: 

Sets the background color generated by graphics functions 
such as GpiCharStringAt. 

Prototype: 

BOOL APIENTRY GpiSetBackColor 
(hps hps, Handle to the presentation space. 

long lCoior ) ; The color value; the following basic 

colors can be specified: 

CLRWHITE 

CLRBLACK 

CLRBLUE 

CLRRED 

CLRPINK 

CLR_GREEN 

CLRCYAN 

CLRYELLOW 

Alternatively, you can specify one of 
the following identifiers: 

Identifier Meaning 

CLR BACKGROUND Default window color 

CLR NEUTRAL Default foreground 

color 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

If the mode set by GpiSetBackMix is BMJLEAVEALONE 
(the default), the background color set by this function will 
not be drawn. 

Related Functions: 

GpiCharStringAt (Figure 3.28) 

GpiSetBackMix (Figure 9.8) 

• Figure 9.9: 

The GpiSetBackColor Presentation Manager function 
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• Restore the cursor visibility by calling WinShowCursor, passing 
a value of TRUE as the second parameter. 

® Call WinReleasePS (Figure 3.22) to release the presentation 
space. 

See also the section in Chapter 6 on Enhancements for more informa¬ 
tion on using the functions mentioned in this list. 

The clipboard commands are normally accessed through a Presenta¬ 
tion Manager submenu entitled Edit. Each of the commands within this 
submenu typically has an associated accelerator key that allows the 
user to quickly execute the command without going through the menu. 
Table 9.1 summarizes these commands. 


• Table 9.1: Edit Menu Commands 


Menu 

Menu 

Accelerator 

Action 

Command 

Mnemonic 

Key 


Cut 

t 

Shift-Del 

Copies selection 
to the clipboard 
and deletes 
selected text from 
program 

Copy 

c 

Ctrl-Ins 

Copies selection 
to the clipboard 
and leaves 
selected text in 
program 

Paste 

p 

Shift-Ins 

Copies current 
contents of the 
clipboard into the 
program data 

Clear 

1 

Del 

Deletes selection 
from program 
without adding it 
to the clipboard 
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In the table, the menu command is the suggested label that appears in 
the Edit pull-down submenu. The menu mnemonic is the recommended 
underlined letter within this label that can be used to quickly select the 
associated command once the Edit submenu is displayed. The table also 
gives the recommended accelerator keystrokes for each command; the 
menu should display each of these keystrokes next to the associated 
menu item. 

The menu added to the example program in Chapter 7 includes an 
Edit submenu with items for the Cut, Copy, and Paste commands. This 
submenu is illustrated in Figure 9.10. Remember that the client window 
receives a WM_COMMAND message, accompanied by the identifier of 
the menu item, whenever the user selects one of these menu items or 
presses the associated accelerator key. The final version of the example 
program processes each of these messages by simply displaying a mes¬ 
sage informing the user that the command has not been implemented. 
You can fully implement each of these three commands using the tech¬ 
niques presented in this chapter and in the first part of the book. 

To execute the Copy command, you could add a function to the buff¬ 
er-management module to copy the selected data directly from the 
Presentation Manager heap into the shamble segment allocated for 
the clipboard. The routine for the Cut command could begin by calling 



• Figure 910: 

The Edit submenu of the example program 
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this same function, and then call another buffer-management function 
for deleting the current selection from the heap. The Paste routine could 
call a third additional buffer-management function to copy the data 
from the sharable segment obtained from the clipboard, and insert 
these data directly into the heap. Finally, after closing the clipboard, the 
routines for the Cut and Paste commands should call Winlnvalidate- 
Rect to invalidate the entire client window, and then call WinUpdate- 
Window to force the WM_PAINT routine to properly display the newly 
modified file data. 

Note that adding a clipboard interface to the text editor would allow 
the user to transfer data between separate instances of this program 
running in distinct windows. Thus, the user can load different files into 
separate program instances and have a program that acts like a stand¬ 
ard editor that opens multiple files and provides cutting and pasting of 
data among these files. (Remember that additional program instances 
load quickly because the code segments are already present in memory, 
and consume a moderate amount of memory because these code seg¬ 
ments are shared.) 


OTHER FEATURES 

• OF THE CLIPBOARD 

This section briefly introduces the following three additional fea¬ 
tures of the Presentation Manager clipboard facility: 

« Alternative clipboard formats 

« The clipboard viewer window 

• Delayed rendering of clipboard data 

Note that some of the functions referenced in this section do not have 
accompanying explanatory figures; you can obtain more information 
on these functions and on the techniques discussed here from the 
Presentation Manager technical references (see the Bibliography). 
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Alternative Clipboard Formats 

A data selection placed into the clipboard can use one of a variety 
of formats. When you call WinSetClipbrdData to add a block of data to 
the clipboard, you must pass this function a 16-bit value that identifies 
the format. The application can define its own format, which is known 
as a private format. More commonly, however, it uses one of the pre¬ 
defined standard formats, which can be recognized and used by a wide 
variety of receiving applications. The following table lists the standard 
clipboard formats: 


Standard Identifier Data Format 


CFJTEXT 

cf_bitmap 

CFJVfETAFILE 

CF_DSPTEXT 

CF_DSPBITMAP 


Text format (described in the section 
on Adding Data to the Clipboard) 

Bitmap format (described in Chapter 10) 

Metafile format 

Text display format associated with a 
private format 

Bitmap display format associated with 
a private format 


As you have seen, the CFJTEXT format is used to exchange standard 
textual data. The CF_BITMAP and CF_METAFILE formats are used to 
exchange graphical data. A block of graphical data stored in the 
CFJBITMAP format is known as a bitmap , and consists of a sequence of 
off and on bits that indicate the values of the actual screen pixels used to 
create the image (bitmaps are discussed further in Chapter 10). A block 
of graphical data stored in the CF_METAFILE format is known as a 
metafile. Like a bitmap, a metafile stores a graphic image; however, 
rather than storing each of the actual pixel values, a metafile stores the 
sequence of Presentation Manager commands that are required to 
recreate the image. Accordingly, a bitmap is displayed by copying the 
bit values directly to video memory, while a metafile is displayed by 
replaying the sequence of commands that it stores. 

Both bitmaps and metafiles can be stored in disk files or within 
memory. When stored in memory, bitmaps and metafiles are identified 
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by handles. Once a program has a handle to a bitmap or metafile in 
memory, it can display the image or perform other operations on the 
data. When an application places a bitmap or metafile into the clip¬ 
board, it must furnish the corresponding handle; when an application 
obtains a bitmap or metafile from the clipboard, it receives the cor¬ 
responding handle. Therefore, just as a block of textual data is ex¬ 
changed through the clipboard by means of the far address of the 
sharable segment containing the data, bitmaps and metafiles are ex¬ 
changed by means of their handles. 

Note that an application can insert a given set of data into the clip¬ 
board in more than one format so that a wider variety of receiving ap¬ 
plications can make use of the data. A receiving application can call the 
Presentation Manager function WinEnumClipbrdFmts to obtain a list 
of the formats currently contained in the clipboard; it can then request a 
data block in the format that is most convenient. 

When an application adds to the clipboard a block of data that has a 
format defined by the application (a private format), it can insert an ad¬ 
ditional block of data that conforms to a standard text or bitmap format. 
An additional block in text format is identified by the value 
CF_DSPTEXT, and an additional block in bitmap format is identified by 
the value CF_DSPBITMAP. These additional blocks are used specifical¬ 
ly by the clipboard viewer window , described in the next section. As you 
will see, the clipboard viewer window displays the current clipboard 
contents, and may be managed by another application (that is, not the 
window viewer application), which may be unable to interpret the pri¬ 
vate format. The clipboard viewer program will display a block of data 
in the CF_DSPTEXT or CF_DSPBITMAP format in preference to a block 
in a private format. 


The Clipboard Viewer Window 

An application can register a clipboard viewer window by calling 
the Presentation Manager function WinSetCIipbrdViewer. A clipboard 
viewer window is responsible for displaying the current contents of the 
clipboard, and it is sent the WM_DRAWCLIPBOARD message when¬ 
ever the clipboard data change. Only one such window can be 
registered at a given time. 
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Note that a clipboard viewer window may not be able to interpret 
and display a privately formatted data selection placed in the clipboard 
by another application. However, as mentioned in the previous section, 
the other application may have provided an alternative data selection 
conforming to a standard format that can be displayed by the viewer 
window procedure. The viewer window should display these formats 
(identified by CF_DSPTEXT and CF_DSPBITMAP) in preference to any 
other formats in the clipboard. 

Also, when an application calls WinSetClipbrdData to insert 
privately formatted data into the clipboard, it may specify the flag 
CFI_OWNERDISPLAY, which means that the calling application itself 
is responsible for displaying this data within the clipboard viewer win¬ 
dow (see Figure 9.3). (More precisely, this flag indicates that the current 
clipboard owner window is responsible for displaying the data. The ap¬ 
plication that inserts these data must therefore first call WinSetClipbrd- 
Owner to establish its window as the current clipboard owner. The 
owner window is subsequently sent a WM_PAINTCLIPBOARD mes¬ 
sage whenever the clipboard viewer window needs repainting. Note 
that the clipboard owner window and the clipboard viewer window are 
typically separate windows; the clipboard owner is given the task of 
repainting the clipboard viewer window only if the data selection has 
been assigned the CFI_OWNERDISPLAY flag.) 


Delayed Rendering of Clipboard Data 

Preparing a block of data and inserting it into the clipboard (a 
process known as rendering the data) may be a lengthy operation. There¬ 
fore, the Presentation Manager allows a program to postpone rendering 
the data until an application actually requests the specific format. 
Delayed rendering is accomplished through the following steps: 

@ The program should call WinSetClipbrdOwner to register a clip¬ 
board owner window. 

e When the program calls WinSetClipbrdData to insert the data 
into the clipboard, it should specify the appropriate format 
(through the third parameter), but pass a NULL data handle (as 
the second parameter). 
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• When an application calls WinQueryClipbrdData to request the 
specified block, the system sends the owner window a 
WM_RENDERFORMAT message. 

® In response to this message, the owner window should render 
the data. To render the data, the window procedure must 
prepare the data and call WinSetClipbrdData again, this time 
supplying the actual data handle for the given format. 

Note that delayed rendering is especially useful for an application 
that provides multiple alternative data formats. It need render only the 
clipboard formats that are actually requested. 
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C hapter 7, which discussed menus and accelerator keys, 
introduced the topic of Presentation Manager resources. 
Chapter 8 then described dialog boxes, which are 
another important resource. This chapter continues the 
treatment of resources with a discussion of icons, pointers, bitmaps, 
strings, and programmer-defined resource types. 


• ICONS AND POINTERS 

An icon is a fixed-size graphic image that you can design and dis¬ 
play from your Presentation Manager application. The most common 
use for an icon is to represent the program window when it has been 
minimized. If you install a custom icon, the system will automatically 
display this icon whenever the application window is minimized. (If 
you do not install an icon, the system displays a small image of the cur¬ 
rent program window, which may not clearly identify the application to 
the user.) As you will see in this section, the application can also display 
an icon within the client window or within a dialog box. 

This section first describes how to design an icon using the Icon 
Editor. It then explains how to install an icon so that it is displayed 
when the application window is minimized, and how to explicitly dis¬ 
play the icon within the client window or within a dialog box. Finally, it 
introduces the closely related topic of mouse pointers, which are 
described fully in Chapter 13. 

The topics in this section are illustrated by the Presentation Manager 
application presented in Figures 10.1 through 10.6. This program in¬ 
stalls an icon that the system automatically displays when the window 
is minimized. It also explicitly displays this same icon within the client 
window, and provides an "About" dialog box that displays the icon in 
addition to a line of text and an OK push button. Figure 10.1 provides a 
MAKE file for preparing this program; Figure 10.2 lists the linker defini¬ 
tion file; Figure 10.3 contains the dialog box resource script generated 
by the Dialog Box Editor; Figure 10.4 gives the general resource script; 
Figure 10.5 provides the header file, which is included in the listings of 
Figures 10.4 and 10.6; and Figure 10.6 lists the C source code. 
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# Figure 10.1 

# 

# This MAKE file prepares the program of Figures 10.1 through 10.6 

# 

FIG10_6.OBJ : FIG10_6.C FIG10_5.H 
cl /W2 /c /Zp /G2ws FIG10_6.C 

FIG10_6.EXE : FIG10_3.DLG FIG10_4.RC FIG10_5.H FIG10 6.ICO 
rc /r FIG10_4.RC 

FIG10_6.EXE : FIG10_6.0BJ FIG10_2.DEF FIG10_4.RES 

link /NOD FIG10_6.OBJ,, NUL, OS2.LIB SLIBCE.LIB, FIG10 2.DEF 
rc FIG10_4.RES FIG10 6.EXE ~ 


• Figure 10.1: 

A MAKE file for preparing the program of Figure 10.6 


; Figure 

10.2 

; Linker 

definition file for the program listed in Figure 10.6 

NAME 

FIG10 6 

PROTMODE 


HEAPSIZE 

1024 

STACKSIZE 

8192 

EXPORTS 

WndProc 


AboutProc 


® Figure 10.2: 

Linker definition file for the program of Figure 10.6 


/* 

Figure 10.3 

Dialog resource script for the program of Figure 10.6 

*/ 

DLGTEMPLATE 256 LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "", 256, 119, 31, 82, 84, FS_NOBYTEALIGN | FS_DLGBORDER I 
WSJVISIBLE | WS_CLIPSIBLINGS I WS SAVEBITS 

BEGIN 

CONTROL "Icon Demo", -1, 4, 67, 75, 10, WC_STATIC, SS_TEXT I 
DT_CENTER | DT_TOP | WS_GROUP | WS_VISIBLE 
CONTROL 1, -1, 33, 30, 16, 32, WC_STATIC, SS_ICON I WS GROUP I 
WS_VISIBLE 

CONTROL "Ok", 1, 24, 7, 35, 12, WC_BUTTON, BS_PUSHBUTTON I BS DEFAULT 
WS_TABSTOP | WSJVISIBLE 

END 

END 


® Figure 103: 

Dialog box resource script for the program of Figure 10.6 
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/* 

Figure 10.4 

General resource script for the program of Figure 10.6 


#include <OS2.H> 

#include "FIG10_5.H" 

POINTER ID_FRAME_RESOURCE FIG10_6.ICO 

MENU ID_FRAME_RESOURCE 
BEGIN 

MENUITEM "About", ID_ABOUT 
END 

rcinclude FIG10_3.DLG 


« Figure 10 A: 

General resource script for the program of Figure 10.6 


/* 

Figure 10.5 

Header file included in Figure 10.6 and Figure 10.4 

V 

#define ID_FRAME_RESOURCE 1 

#define ID_AB0UT 10 

#define ID_ABOUTDLG 256 


«♦ Figure 10.5: 

Header file included in the listings of Figures 10 A and 10.6 
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/* 

Figure 10.6 

This program demonstrates the use of an icon. 

*/ 

#define INCL_WIN 
#include <0S2.H> 

#include "FIG10 5.H" 


MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


void main () 

{ 

HAB HAncBlk; 

HMQ HMesQue; 

HWND HFrame, HClient; 

QMSG Qu^Mess; 

ULONG CtlData = 
FCF_MENU 
FCF_MINMAX 
FCF_SHELLPOSITION 
FCF_SIZEBORDER 
FCF_SYSMENU 
FCF_TASKLIST 
FCF_TITLEBAR; 


/* Anchor block handle. */ 
/* Message queue handle. */ 
/* Frame/client window handles. */ 
/* Message queue structure. */ 
/* Control windows to include: */ 
/* Menu. */ 
/* Minimize/maximize box. */ 
/* Make window visible on screen. */ 
/* Wide sizing border. */ 
/* System menu. */ 
/* Display program name in Task Manager. */ 
/* Title bar. */ 


HAncBlk = Winlnitialize 
( 0 ) ; 


/* Initialize the PM. */ 

/* Initialization options: must be 0. */ 


HMesQue = WinCreateMsgQueue /* Create a message queue. */ 

(HAncBlk, /* Anchor block handle. */ 

°) /* Minimum queue size: 0 means default size.*/ 


WinRegisterClass /* Register window class for client window. */ 

(HAncBlk, /* Anchor block handle. */ 

"MAIN", /* Window class name. */ 

WndProc, /* Window procedure associated with class. */ 

CS _ SIZEREDRAW / /* Invalidate entire window on size change. */ 

°) '* /* Bytes of data storage for each window. */ 


/*** create standard window and load icon. ***********************************/ 


HFrame = WinCreateStdWindow 
(HWND_DESKTOP, 
WS_VISIBLE | 

FS_IC0N, 

&CtlData, 

"MAIN", 

": Icon Demo", 

0L, 

0 , 

ID_FRAME_RESOURCE, 
SHClient)? 


/* Create a standard window collection. */ 
/* Parent window handle. */ 
/* Frame window style: visible. */ 
/* Load an icon. */ 
/* Address of control data. */ 
/* Client window class name. */ 
/* Text for title bar. */ 
/* Client window style: none specified. */ 
/* Resource module handle: EXE file. */ 
/* Resource identification. */ 


/* Address to receive client window hand. */ 


© Figure 10.6: 

An application illustrating the use of icons 
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while (WinGetMsg 
(HAncBlk, 
SQueMess, 

0 , 

0 / 

0 )) 


WinDispatchMsg (HAncBlk,SQueMess); 

/* Dispatch messages. 

V 

WinDestroyWindow (HFrame); 


/* Eliminate the window. 

V 

WinDestroyMsgQueue (HMesQue) 

; 

/* Eliminate the message queue. 

*/ 

WinTerminate (HAncBlk) 

; 


/* Sever ties with the 

Presentation 

*/ 




/* Manager and release 

resources. 

*/ 

} /* end main */ 







MRESULT EXPENTRY AboutProc 

(HWND 

hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2); 


MRESULT EXPENTRY Command 

(HWND 

hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2); 


MRESULT EXPENTRY Create 

(HWND 

hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2); 


MRESULT EXPENTRY Destroy 

(HWND 

hwnd, 

, USHORT msg, 

MPARAM mpl, 

MPARAM mp2); 


MRESULT EXPENTRY Paint 

(HWND 

hwnd, 

, USHORT msg, 

, MPARAM mpl, 

MPARAM mp2)? 


HPOINTER HIcon; 

/*' 

Icon 

handle. 



*/ 

MRESULT EXPENTRY WndProc 







(HWND hwnd, 

/* 

Window handle. 



V 

USHORT msg, 

/* 

The message. 



*/ 

MPARAM mpl, 

/* 

Message-specific 

information. 


*/ 

MPARAM mp2) 

/* 

Message-specific 

information. 


*/ 

{ 

switch (msg) 







{ 

case WM_CREATE: 

/* 

Sent 

when window 

is first created. 

*/ 


return Create (hwnd, msg, mpl, mp2); 
case WM_DESTROY: /* Sent when window is destroyed. */ 

return Destroy (hwnd, msg, mpl, mp2); 
case WM_COMMAND: /* Process messages from menu. */ 

return Command (hwnd, msg, mpl, mp2); 
case WM_PAINT: /* Process window paint message. */ 

return Paint (hwnd, msg, mpl, mp2)? 
default: /* Perform the default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} 

} /* end WndProc */ 


/* Get messages until WM_QUIT. */ 
/* Anchor block handle. */ 
/* Address of message structure. */ 
/* Window filter: any window. */ 
/* First message identifier: n/a. */ 
/* Last message identifier: n/a. */ 


• Figure 10,6: 

An application illustrating the use of icons (continued) 
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MRESULT EXPENTRY AboutProc (HWND hwnd, USHORT msg, 

switch (msg) 

{ 

case WM_COMMAND: 


MPARAM mpl, MPARAM mp2) 


switch (COMMANDMSG(&msg)->cmd) 

{ 

case DID__OK: 
case DID_CANCEL: 

WinDismissDlg (hwnd,TRUE); 
return FALSE; 


default: 

return FALSE; 

} 

default: 

return WinDefDlgProc (hwnd, msg, mpl, mp2); 
} /* end AboutProc */ 


MRESULT EXPENTRY Command (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 
USHORT Result; 


switch (COMMANDMSG (&msg)->cmd) 

{ 

case ID_ABOUT: /* 'About' item 'File' submenu. */ 

Result = WinDlgBox /* Display 'About' dialog box. */ 

(HWND_DESKTOP, /* Handle of parent window; desktop. */ 

hwnd, /* Handle of owner: client. */ 

AboutProc, /* Dialog procedure. */ 

NULI u /* Resource module: the .EXE file. */ 

ID_ABOUTDLG, /* Name ID of dialog window: About. */ 

NULL); /* Pointer to procedure data: n/a. */ 


return FALSE; 

default: 

return FALSE; 

} 

} /* end Command */ 


MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/*** Load the icon. **********************************************************y 
HIcon = WinLoadPointer 

(HWND_DESKTOP, /* Handle of desktop window. */ 


• Figure 10.6: 

An application illustrating the use of icons (continued) 
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null, /* Module handles EXE file. */ 

ID_FRAME_RESOURCE); /* Resource identifier. */ 

return FALSE? 

} /* end Create */ 


MRESULT EXPENTRY Destroy (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/*** Remove the icon resource from memory. ***********************************/ 


WinDestroyPointer 
(HIcon); 

return FALSE; 

) /* end Destroy */ 


/* Icon handle. 


MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


HPS HPresSpace; /* Presentation space handle. */ 

RECTL Rect? /* Window rectangle, in window coordinates. */ 

static char Message [] = /* Text to display. */ 

"This window displays an icon."; 

HPresSpace = WinBeginPaint /* Returns presentation space handle. */ 

(hwnd, /* Window handle. */ 

0, /* o requests a cache presentation space. */ 

0)? /* Address of variable to set to invalid region: none.*/ 

WinQueryWindowRect /* Obtain coordinates of client window. */ 

(hwnd, /* Window handle. */ 

&Rect) ? /* Structure to receive coordinates. */ 

WinDrawText /* Draws a single line of formatted text into a rectangle. */ 
(HPresSpace, /* Presentation space handle. */ 

Oxffff, /* Length of string: Oxffff means 0 terminated.*/ 

Message, /* Text to be displayed. */ 

&Rect, /* Coordinates of rectangle containing text. */ 

CLR_BLACK, /* Foreground color. */ 

CLR_WHITE, /* Background color. */ 

/* Drawing specifications: */ 

DT_CENTER I /* Center text horizontally. */ 

DT_VCENTER | /* Center text vertically. */ 

DT_ERASERECT); /* Erase the rectangle (entire window). */ 


/*** Draw the icon. **********************************************************/ 
WinDrawPointer 


(HPresSpace, 

/* Presentation space handle. 

V 

0 , 

/* Horizontal coordinate. 

*/ 

0 , 

/* Vertical coordinate. 

V 

HIcon, 

/* Icon handle. 

*/ 


® Figure 10.6: 

An application illustrating the use of icons (continued) 




• Figure 10.6: 


An application illustrating the use of icons (continued) 

Designing an Icon 

The first step is to design the icon using the Icon Editor, 
ICONEDIT.EXE. The Icon Editor is a Presentation Manager application 
that provides a rectangular drawing area having the proportions of a 
standard icon. You can use the mouse to draw the desired icon within 
this area, pixel-by-pixel. You can assign each of these pixels one of the 
following four colors: 

Color Visual Effect 

Black Pixel displayed as black 

White Pixel displayed as white 

Screen Screen color underlying pixel is displayed 

Inverse-screen Screen color underlying pixel is inverted 

The left mouse button toggles between the black and white colors, and 
the right mouse button toggles between the screen and inverse-screen 
colors. Pixels that are assigned the screen color show the underly¬ 
ing color of the screen and are thus invisible. Pixels assigned the in¬ 
verse-screen color always contrast with the underlying color; for 
example, if the current underlying color is yellow, the icon pixel will be¬ 
come the inverse color, blue. 

Figure 10.7 illustrates the Icon Editor containing the icon that is dis¬ 
played by the application of Figure 10.6. The rectangular area on the 
right is the editing window used to draw the icon, which is displayed 
much larger than its actual size. The rectangular area on the left is the 
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viewing window, which displays a true scale replica of the icon. The 
icon depicted in Figure 10.7 has a white background with a black border 
and black letters; it is thus visible over any background screen color. 
Note that assigning certain color combinations may render the icon in¬ 
visible when it is displayed on top of some backgrounds; for example, 
an icon that is given a screen-colored background and a black 
foreground will disappear when displayed within a black screen area. 

Before you create a new icon with the Icon Editor (through the New 
item of the File submenu), you must specify the number of pixels that 
the icon is to contain. You can choose one of the following values: 


Resolution Pixels 

(width x height) 

Low 32x16 

Medium 32 x 32 

High 64 x 64 


Display Adapter Type 

CGA 

Standard EGA or VGA 
Higher-resolution systems 


The editing window allows you to manipulate the designated num¬ 
ber of pixels, and the value of each of these pixels is recorded in the file 
that stores the icon image. However, because an icon displayed on the 





le Edit Options Color Pen Size Exit 


Use the mouse to edit the icon. Button 1 toggles black/White. Button 2 
toggles screen/inverse screen. 


ICON 

Med-res 32x32 
Med-res 32x32 


type.: 

editing.: 

viewing: 


© Figure 10.7: 

The Icon Editor with an example icon 
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screen always has approximately the same size, the actual number of 
pixels used to draw the icon depends upon the current screen resolu¬ 
tion. For example, if you create an icon with 32 % 16 pixels (the number 
of pixels used to draw the icon with a CGA adapter), and then display 
the icon with an EGA system, the Presentation Manager must duplicate 
every other row of pixels. Likewise, if you designate an icon with 64 % 
64 pixels and then display this icon on a EGA system, the Presentation 
Manager must eliminate every other row and column. Because adding 
or removing pixels degrades the original image designed in the Icon 
Editor, it is best to designate the same number of pixels that will ul¬ 
timately be used to display the icon. However, if the program must run 
on a variety of target machines, the best choice might be the medium 
resolution, 32 % 32 pixels. 

When you have completed designing the icon, you should save the 
data in a file through the File submenu. If you do not specify a file ex¬ 
tension, it is automatically given the .ICO extension. For further infor¬ 
mation, see the documentation and online help information provided 
with the Icon Editor. 


Installing an Icon 

This section describes how to associate an icon with the standard 
window so that the system automatically displays this icon when the 
application window is minimized. 

First, because the data for an icon is stored as a Presentation Manager 
resource, you must write a script to direct the resource compiler to in¬ 
clude these data in a resource segment in the executable file. An icon is 
defined within the resource script with the keyword POINTER, fol¬ 
lowed by an identifier and the name of the file generated by the Icon 
Editor. The example resource script in Figure 10.4 assumes that the icon 
created with the Icon Editor was saved in the file FIG10_6.ICO, and it 
defines the icon using the following line: 

POINTER ID_FRAME_RESOURCE FIG10_6.ICO 

Note that if you are going to associate an icon with the standard win¬ 
dow, and if the application also uses a menu or accelerator table, you 
must assign the icon the same identifier used for the menu and 
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accelerator table. When the resource compiler encounters the icon 
definition, it obtains the icon data from the specified file and inserts 
these data directly into the binary resource file (.RES), which will sub¬ 
sequently serve as the source of the data inserted into the program file. 
See the MAKE file of Figure 10.1 for the commands used to prepare the 
program resources, and see Chapter 7 for a general discussion on using 
the resource compiler. 

If icon data are contained within a resource segment in the executable pro¬ 
gram, you can associate the icon with the standard window simply by in¬ 
cluding the appropriate parameters in the call to WinCreateStdWindow 
(Figure 2.5). The program of Figure 10.6 calls this function as follows: 


HFrame = WinCreateStdWinow 


(HWND DESKTOP. 

/* 

Parent window handle. 

*/ 

WS_VISIBLE | 

/* 

Frame window style: visible. 

*/ 

FS_ICON 

/* 

Load an icon. 

*/ 

SCtlData, 

/* 

Address of control data. 

*/ 

"MAIN", 

/* 

Client window class name. 

*/ 

"Icon Demo", 

/* 

Text for title bar. 

*/ 

0L, 

/* 

Client window style: 

*/ 


/* 

none specified. 

*/ 

o, 

/* 

Resource module handle: 

*/ 


/* 

.EXE file. 

*/ 

ID FRAME RESOURCE 

/* Resource identifier. 

*/ 

SHClient); 

/* 

Address to receive 

*/ 


/* 

client window hand. 

*/ 


The following three parameters passed to WinCreateStdWindow 
cause the system to associate the icon with the standard window: 

« The frame style parameter (the second parameter, flStyle) in¬ 
cludes the constant FS_ICON, which indicates that an icon is to 
be loaded and displayed when the window is minimized. 

e The module handle parameter (the seventh parameter, hmod) is 
given a value of 0, indicating that the resource segment contain¬ 
ing the icon data is located within the executable file. (Alterna¬ 
tively, if the icon data were contained in a dynamic-link library 
file, you would have to first call DosLoadModule to explicitly 
load these data, and then pass the module handle returned by 



502 Programmer's Guide to the OS/2 Presentation Manager 


DosLoadModule as the hmod parameter to WinCreateStd- 
Window.) 

• The resource identifier parameter (idResources, the eighth 

parameter) is given the value ID_FRAME_RESOURCE, which is 
the identifier assigned to the icon in the resource script. 

Once a custom icon has been associated with the standard window 
through the call to WinCreateStdWindow, the system automatically 
displays this icon whenever the user minimizes the window; no further 
program action is required to manage the icon. 


Displaying an Icon 
within the Client Window 

If you have designed an icon and included the icon data in a pro¬ 
gram resource segment as described in the previous section, you can 
also display the icon at any position within the client window. To ex¬ 
plicitly display the icon in the client window, you should perform the 
following three steps from the client window procedure: 

• Call the WinLoadPointer Presentation Manager function (Figure 
10.8) to load the icon data from the resource segment into 
memory. 

• Call WinDrawPointer (Figure 10.9) to display the icon at a 
specified position within the window. To call this function, you 
must have a valid handle to a presentation space. 

• When you have completed displaying the icon, call the Win- 
DestroyPointer function (Figure 10.10) to release the memory 
containing the icon data. 

Note that rather than creating a custom icon, and obtaining a handle 
to this icon by calling WinLoadPointer, you can obtain the handle to a 
pointer provided by the system by calling the WinQuerySysPointer 
function (Figure 11.7). System icons can be displayed within the client 
window by calling WinDrawPointer. Chapter 11 explains the Win¬ 
QuerySysPointer function and illustrates the system icons. 
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WinLoadPointer 

Purpose: 

Loads an icon or mouse pointer into memory from a 

resource segment contained in a disk file. 

Prototype: 

HPOINTER APIENTRY WinLoadPointer 

(hwnd hwndDesktop, The identifier of the desktop window, 
HWNDJDESKTOP. 

hmodule hmod, Resource module handle; if the 

resource is contained within the 
executable file, this parameter must be 
assigned NULL; if the resource is in a 
dynamic-link module, the parameter 
must contain the module handle 
returned by DosLoadModule. 

ushort idres) ; The identifier assigned to the icon or 

pointer in the resource script. 

Return Value: 

The handle of the newly loaded icon or pointer, or the value 

NULL if an error occurred. 

Notes: 

When the resource loaded by this function is no longer re¬ 
quired, it should be released by calling WinDestroyPointer. 

Related Functions: 

WinDestroyPointer (Figure 10.10) 


• Figure 10.8: 

The WinLoadPointer Presentation Manager function 
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WinDrawPointer 

Purpose: 

Draws an icon. 

Prototype: 

BOOL APIENTRY WinDrawPointer 
(HPS hps, 


SHORT x. 


SHORT 


HPOINTER hptr, 
USHORT fs); 


Handle of the presentation space in which 
the icon is to be drawn. 

x-coordinate of position where lower left 
corner of icon should be placed. 

y-coordinate of position where lower left 
corner of icon should be placed. 

Handle of the icon returned by 
WinLoadPointer. 

Flags specifying how the icon is to be drawn; 
you can choose from the following values: 


Value 

DP_NORMAL 

DPHALFTONED 


DPJNVERTED 


Effect 

Draw the icon 
without modification 

Draw the black areas 
of the icon with a 
half toned pattern 

Invert the icon colors; 
that is, substitute 
black for white and 
white for black 


Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 


Related Functions: 

WinLoadPointer (Figure 10.8) 


® Figure 10.9: 

The WinDrawPointer Presentation Manager function 
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WinOestroyPointer 

Purpose: 

Destroys an icon or pointer. 

Prototype: 

BOOL APIENTRY WinDestroyPointer 

(hpointer hptr) ; Pointer handle returned by 

WinLoadPointer. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Related Functions: 

WinLoadPointer (Figure 10.8) 


• Figure 10.10: 

The WinDestroyPointer Presentation Manager function 

The window procedure in the example program of Figure 10.6 calls 
WinDrawPointer to display the icon within the client window each 
time it receives the WM_PAINT message (Figure 2.19). So that the icon 
handle will be available throughout the lifetime of the window, the pro¬ 
gram calls WinLoadPointer during the processing of the WM_CREATE 
message (Figure 3.16; remember that this message is sent when the win¬ 
dow is first created, before the initial WM_PAINT message). The 
WM_CREATE message is handled by the function Create, which calls 
WinLoadPointer as follows: 

HPOINTER HIcon; 


HIcon = WinLoadPointer 

(HWND DESKTOP, /* Handle of desktop window. */ 
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/* Module handle: .EXE file. */ 
ID_FRAME^JRESOURCE); /* Resource identifier. */ 

Note that HIcon is declared as an external variable; therefore, the icon 
handle that it receives from WinLoadPointer will be available for sub¬ 
sequent use by the WM_PAINT routine. 

Before the window is destroyed, the client window procedure calls 
WinDestroyPointer to free the memory occupied by the icon data. The 
client window is notified of its impending destruction through the 
WM_DESTROY message (Figure 10.11). The function that processes this 
final message. Destroy, calls WinDestroyPointer as follows: 

WinDestroyPointer 

(HIcon); /* icon handle. */ 


WM_DESTROY 

Purpose: 

This message is sent by the system to a window when it is 
about to be destroyed. 

Parameters: 

MPARAM mpl NULL. 

MPARAM mp2 NULL. 

Return Value: 

NULL. 

Notes: 

This message is sent to the window procedure after the win¬ 
dow has been hidden on the screen, and it allows the ap¬ 
plication to perform any final tasks required before the 
window is destroyed. 


@ Figure 10.11: 

The WM_DESTROY Presentation Manager message 
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The program of Figure 10.6 processes the WMJPAINT message in the 

function Paint. This function performs the following series of steps: 

1. It calls WinBeginPaint to obtain a handle to a presentation space. 

2. It calls WinQueryWindowRect to obtain the current coordinates 
of the client window in a RECTL structure. 

3. In calls WinDrawText to display a single line of text in the center 
of the window. 

4. It calls WinDrawPointer to display the icon at the lower left 
corner of the window. 

5. It calls WinEndPaint to release the handle to the presentation 
space and to notify the system that the window has been 
updated. 

The call to WinDrawPointer is as follows: 


WinDrawPointer 

(HPresSpace, /* Presentation space handle. */ 
0, /* Horizontal coordinate. */ 
0, /* Vertical coordinate. */ 
HIcon, /* Icon handle. */ 


DP NORMAL); /* Flag: normal pointer appearance. */ 

Note that the second and third parameters supply the location within 
the client window where the system places the lower left corner of the 
icon; this call therefore causes the icon to appear in the lower left corner 
of the window, touching the left and bottom window edges. You do not 
need to specify the dimensions of the icon, since it is drawn with a fixed 
size (the icon is always given the same size, whether it is used to repre¬ 
sent a minimized window, or is drawn within the client window or 
within a dialog box). Alternatively, bitmaps, which are discussed later 
in the chapter, can be drawn to fill any given rectangular dimensions. 

You may have noticed that the call to WinRegisterClass in the ex¬ 
ample program of Figure 10.6 specifies the CS_SIZEREDRAW style 
(explained in Table 2.1). This style forces the system to invalidate the en¬ 
tire client window (and thus send a WMJPAINT message) whenever 
the user changes the window size. Previous examples in the book did 
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not require this style, because all data displayed by these programs 
were aligned with respect to the upper left corner of the client window, 
and the system automatically realigns data with respect to this corner 
whenever the window size is changed. (If the CS_SIZEREDRAW style 
is not specified, the system does not invalidate the window or send a 
WM_PAINT message when the window size is reduced; when the win¬ 
dow is enlarged, the system sends a WM_PAINT message but in¬ 
validates only the newly exposed area.) The current example program, 
however, justifies the text string in the center of the window, and aligns 
the icon with the lower left corner of the window. Thus, the 
CS_SIZEREDRAW style is mandated (you might try recompiling the 
program without this style to observe the difference). 

A note about erasing the client window: Unlike the WM_PAINT routines 
presented previously in the book, the current version of Paint does not call 
WinFillRect to explicitly erase the client window. Rather, when this func¬ 
tion calls WinDrawText (Figure 2.24), it includes the value DTERASE- 
RECT within the flag parameter (the last parameter), as follows: 

WinDrawText 


(HPresSpace, 

/* Presentation space handle. 

*/ 

Oxffff, 

/* Length of string: 

*/ 


/* Oxffff means 0-terminated. 

*/ 

Mess age, 

/* Text to be displayed. 

*/ 

&Rect, 

/* Coordinates of rectangle 

*/ 


/* to contain text. 

*/ 

CLR_BLACK, 

/* Foreground color. 

*/ 

CLR WHITE, 

/* Background color. 

*/ 


/* Drawing specifications: 

*/ 

DT_C ENTER | 

/* Center text horizontally. 

*/ 

DT_VCENTER | 

/* Center text vertically. 

*/ 

DT_ERASERECT); 

/* Erase the rectangle 

*/ 


/* (entire window). 

*/ 


The DTJERASERECT flag causes this function to erase the rectangular 
area given by the fourth parameter (a pointer to a RECTL structure) by 
filling this area with the background color specified through the sixth 
parameter. Because the RECTL structure Rect contains the current coor¬ 
dinates of the client window, the call to WinDrawText effectively erases 



Creating Icons, Bitmaps, and Other Resources 509 a 


the entire window before displaying the string. (The program therefore 
calls WinDrawText before calling WinDrawPointer!) 

Note that when erasing the client window by calling WinFillRect, or 
WinDrawText with the DT_ERASEFLAG, you can specify an explicit 
color value to be used to fill the window, which thereby becomes the 
window background color. You can alternatively specify the value 
CLRJ3ACKGROUND, which refers to the current default background 
color that has been set by the user through the Control Panel utility 
described in Chapter 1. If you specify the default background color by 
passing CLRJBACKGROUND when erasing the client window, you 
should also specify the default foreground color, CLR_NEUTRAL, 
when displaying characters through WinDrawText or GpiCharString- 
At (otherwise, you could end up with an undiscernible color combina¬ 
tion such as white characters on a white background). The possible 
color values are listed in Figure 2.23. 

An alternative method for erasing the client window with the default 
background color is to call the Presentation Manager function GpiErase 
(Figure 10.12), which erases the entire window associated with the 


GpiErase 

Purpose: 

Erases the specified presentation space by filling the area 
with the default system background color (CLRJBACK- 
GROUND). 

Prototype: 

BOOL APIENTRY GpiErase 

(hps hps) ; Handle of the presentation space. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 


@ Figure 10.12: 

The GpiErase Presentation Manager function 
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specified presentation space. You do not specify a background color 
when calling GpiErase; it automatically uses the default background 
color. 

Note that all the example programs in this book specify explicit color 
values a black foreground against a white background—for the sake 
of simplicity and because of some inconsistencies in the manner colors 
were managed in the early versions of the Presentation Manager. 


Displaying an Icon within a Dialog Box 

If you have created an icon and included the icon data as a 
resource in the executable file, you can also display this icon within 
a dialog box. When you are designing a dialog box in the Dialog Box 
Editor, you can add an icon to the collection of dialog controls by select¬ 
ing the Icon control item from the Control submenu. You will notice 
that you can move the icon within the dialog box, but you cannot 
change its size, since an icon is a fixed-size graphic image. Note also 
that when assigning the icon styles, the Text field does not contain a text 
string, but rather must be assigned the identifier of the icon resource that ap¬ 
pears in the POINTER definition in the resource file. You need to assign the 
ID Symbol field a unique value only if you are going to reference 
the icon within the C program. 

The example application of Figure 10.6 displays an About dialog box 
when the user selects the About menu item (which is the only item in 
the program menu). This dialog box is illustrated in Figure 10.13; note 
that it displays the program icon in addition to a text string and a push 
button. Figure 10.14 illustrates the manner in which the icon styles were 
defined in the Dialog Box Editor; the Static Styles box appears when the 
icon control is first positioned and whenever you choose the Styles item 
of the Edit submenu when the icon is selected. Note that the Text field is 
assigned the value 1 (ID_FRAME_RESOUR.CE), which is the identifier 
given to the icon in the POINTER statement within the resource file 
(Figure 10.4). The ID Symbol field is assigned -1, since the icon does not 
need to be referenced within the C source code. 

The program menu is created and managed as described in Chapter 
7, and the About dialog box is displayed and dismissed in the same 
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manner as the About dialog box presented in Chapter 8. The system 
automatically loads and displays the icon, along with the other dialog 
controls, when the dialog box is activated through the WinDlgBox 
function. 



• Figure 1013: 

The About dialog box 
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• Figure 10.14: 

Defining the icon in the Dialog Box Editor 
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Designing a Mouse Pointer 

The structure of the graphic data used to draw a mouse pointer is 
the same as that used for an icon. Accordingly, you can create and load 
a custom mouse pointer in a manner similar to the method employed 
for an icon. Specifically, you should perform the following steps: 

® Design the custom pointer in the Icon Editor, selecting the 

desired resolution. Note that you can select the "screen" color for 
areas outside of a nonrectangular pointer image. Also, when 
designing a pointer in the Icon Editor, you should designate a 
hot-spot pixel through the Edit submenu; the concept of the 
pointer hot spot is explained in Chapter 11. The resulting file will 
be saved with the .PTR extension. 

« Define the pointer in the resource file using the POINTER 

keyword in the same manner as an icon; note, however, that the 
identifier should be distinct from that used for the icon or any 
other pointers you define for the application. 

® Load the pointer data using WinLoadPointer and release these 
data using WinDestroyPointer, in the same manner as an icon. 

® Rather than displaying a pointer with WinDrawPointer (used to 
draw an icon), however, you should call WinSetPointer 
(described in Chapter 11) to force the Presentation Manager to 
use your custom mouse pointer in place of the default system 
pointer. 

Chapter 11 provides an example program that displays a custom 
mouse pointer, and also shows how to use the alternative pointers 
provided by the system, such as the hourglass pointer normally dis¬ 
played during a lengthy operation. 


• BITMAPS 

As stated in Chapter 9, a bitmap is a data structure that stores a 
graphic image; it consists of a sequence of off and on bits that indicate 
the values of the actual screen pixels used to create the image. Bitmaps 
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can be stored in a disk file or in memory. A bitmap is a more versatile 
medium than an icon or a pointer (icons and pointers are actually spe¬ 
cialized forms of bitmaps). A bitmap can store the values of a variable 
number of pixels; it can hold either a monochrome or a color image; and 
the size of a bitmap can be readily adjusted when it is loaded into 
memory or displayed on a device. 

This section discusses how to create a monochrome bitmap using the 
Icon Editor, how to store the bitmap as a Presentation Manager 
resource, and how to display the graphic image stored in the bitmap 
within the client window. The procedures described in this section thus 
use bitmaps as sources of fixed graphics data. Note that an application 
can also create or modify bitmaps at run-time; thus, bitmaps can be 
used to receive graphics data in a manner similar to an output device 
such as a screen or plotter. (To send graphics data to a bitmap at run¬ 
time, you can associate a presentation space with the bitmap, and then 
perform normal graphics operations on this presentation space. This 
topic, however, is beyond the scope of the book, which discusses only 
presentation spaces that are associated with windows.) 

The techniques discussed in this section are illustrated by the ex¬ 
ample application given in Figures 10.15 through 10.19, which loads 
and displays a bitmap so that the graphic image completely fills the 
client window. 

To create a bitmap with the Icon Editor, select the New item of the 
File submenu and choose the Bitmap selection when the dialog box ap¬ 
pears. You must then specify the total number of horizontal and vertical 
pixels you want to work with when you design the bitmap. You can 
choose any number of horizontal and vertical pixels in the range from 1 
to 99 (in contrast to icons and pointers, for which you can select one of 
only three fixed resolutions). Note that the choice of the number of 
pixels will affect the resolution of the final image displayed in the win¬ 
dow, but it will not affect the size of the image; as you will see, the over¬ 
all size and proportions can be adjusted either when you load or when 
you draw the bitmap. 

Designing a bitmap using the Icon Editor is the same as designing an 
icon or pointer, except that you can select only black and white color 
values (as opposed to the four color values used for icons and pointers), 
since the Icon Editor can create only monochrome bitmaps. The bitmap 
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# Figure 10.15 

# 

# This MAKE file prepares the program of Figures 10.15 through 10.19 

# 

FIG10_19.OBJ : FIG10_19.C FIG10_18.H 

cl /W2 /c /Zp /G2ws FIG10_19.C 

FIG10_19.EXE : FIG10_17.RC FIG10_18.H FIG10_19.BMP 
rc /r FIG10_17.RC 

FIG10_19.EXE : FIG10_19.0BJ FIG10_16.DEF FIG10_17.RES 

link /NOD FIG10_19.OBJ,, NUL, OS2.LIB SLIBCE.LIB, FIG10_16.DEF 
rc FIG10 17.RES FIG10 19.EXE 


Figure 10.15: 

A MAKE file for preparing the program of Figure 10.19 


; Figure 10.16 

; Linker definition file for the program listed in Figure 10.19 

NAME FIG10_19 

PROTMODE 

HEAPSIZE 1024 

STACKSIZE 8192 

EXPORTS WndProc 

Figure 10.16: 

Linker definition file for the program of Figure 10.19 


/* 

Figure 10.17 

General resource script for the program of Figure 10.19 


#include <OS2.H> 

#include "FIG10_18.H" 

STRINGTABLE 

BEGIN 

ID_PROGNAME, »: Bitmap Demo” 

END 

BITMAP ID_BITMAP FIG10_19.BMP 

Figure 10.17: 

General resource script for the program of Figure 10.19 
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/* 

Figure 10.18 

Header file to be included in Figure 10.17 and Figure 10.19 


#define ID_PROGNAME 0 
#define ID_BITMAP 1 


® Figure 10.18: 

Header file included in the listings of Figures 10.17 and 10.19 


/* 

Figure 

V 

#define INCL_WIN 
#include <OS2.H> 

#include M FIG10_18.H" 

MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


void main () 

1 

HAB HAncBlk? 


/* Anchor block handle. 

V 

HMQ HMesQue; 


/* Message queue handle. 

V 

HWND HFrame, HClient; 


/* Frame/client window handles. 

*/ 

QMSG QueMess; 


/* Message queue structure. 

*/ 

char ProgName [32]; 


/* Holds program name string. 

*/ 

ULONG CtlData = 


/* Control windows to include: 

V 

FCF MINMAX 


/* Minimize/maximize box. 

*/ 

FCF SHELLPOSITION 


/* Make window visible on screen. 

*/ 

FCF SIZEBORDER 


/* Wide sizing border. 

*/ 

FCF SYSMENU 


/* System menu. 

V 

FCF TASKLIST 


/* Display program name in Task Manager. 

V 

FCF_TITLEBAR; 


/* Title bar. 

*/ 

HAncBlk = Winlnitialize 


/* Initialize the PM. 

*/ 

(0) ? 


/* Initialization options: must be 0. 

*/ 

HMesQue = WinCreateMsgQueue 

/* Create a message queue. 

V 

(HAncBlk 

/ 

/* Anchor block handle. 

*/ 

0) ? 


/* Minimum queue size: 0 means default size 

V 

WinRegisterClass 

/* 

Register window class for client window. 

V 

(HAncBlk, 

/* 

Anchor block handle. 

*/ 

"MAIN" , 

/* 

Window class name. 

*/ 

WndProc, 

/* 

Window procedure associated with class. 

*/ 

CS SIZEREDRAW, 

/* 

Invalidate entire window on size change. 

V 

0) ? 

/* 

Bytes of data storage for each window. 

V 


® Figure 10.19: 

An application that loads and displays a bitmap 
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WinLoadString 






(HAncBlk, 


/* 

Anchor block handle. 

*/ 

NULL, 


/* 

Module handle: in EXE file. 

*/ 

ID PROGNAME, 


/* 

String identifier. 

v 

sizeof (ProgName) 

, 

/* 

Size 

of receiving buffer. 

*/ 

ProgName); 


/* 

Receiving buffer. 

*/ 

j HFrame = WinCreateStdWindow 

/* 

Create a standard window collection. 

*/ 

(HWND DESKTOP, 



/* 

Parent window handle. 

*/ 

WS_VISIBLE, 



/* 

Frame window style: visible. 

*/ 

&CtlData, 



/* 

Address of control data. 

*/ 

"MAIN", 



/* 

Client window class name. 

*/ 

ProgName, 



/* 

Text for title bar. 

*/ 

OL, 



/* 

Client window style: none specified. 

*/ 

0, 



/* 

Resource module handle: n/a. 

*/ 

o, 



/* 

Resource identification: none. 

*/ 

&HClient) ? 



/* 

Address to receive client window hand. 

*/ 

while (WinGetMsg 



/* 

Get messages until WM QUIT. 

*/ 

(HAncBlk, 



/* 

Anchor block handle. 

*/ 

StQueMess, 



/* 

Address of message structure. 

*/ 

0, 



/* 

Window filter: any window. 

*/ 

0, 



/* 

First message identifier: n/a. 

V 

0) ) 



/* 

Last message identifier: n/a. 

V 

WinDispatchMsg (HAncBlk,SQueMess); /* Dispatch messages. 

*/ 

j WinDestroyWindow (HFrame 

; 


/* Eliminate the window. 

*/ 

WinDestroyMsgQueue (HMesQue); 

/* Eliminate the message queue. 

V 

WmTerminate (HAncBlk) 




/* Sever ties with the Presentation 

*/ 





/* Manager and release resources. 

V 

} /* end main */ 






MRESULT EXPENTRY Create 

(HWND 

hwnd 

USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY Destroy 

(HWND 

hwnd 

USHORT msg, MPARAM mpl, MPARAM mp2); 


MRESULT EXPENTRY Paint 

(HWND 

hwnd 

USHORT msg, MPARAM mpl, MPARAM mp2); 


HBITMAP HBitmap; 


/* 

Bitmap handle. 

*/ 

MRESULT EXPENTRY WndProc 






(HWND hwnd, 


/* 

Window handle. 

*/ 

USHORT msg, 


/* 

The message. 

V 

MPARAM mpl, 


/* 

Message-specific information. 

*/ 

MPARAM mp2 ) 

/ 


/* 

Message-specific information. 

V 

\ 

switch (msg) 






i 

case WM_CREATE : 


/* 

Sent 

when window is first created. 

V 

return Create 

(hwnd, msg, mpl, mp2) ; 


case WM_DESTROY : 


/* 

Sent 

when window is destroyed. 

V 

return Destroy 

(hwnd, msg, mpl, mp2) ; 



© Figure 10.19: 

An application that loads and displays a bitmap (continued) 




g Icons, 


case WM PAINT: 


/* Process window paint message. 


return Paint (hwnd, msg, mpl, mp2); 
default: /* Perform the default processing on all other messages. */ 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

} 

} /* end WndProc */ 

MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

{ 

HPS HPresSpace; 

/*** Obtain a handle to a window presentation space. *************************/ 
HPresSpace = WinGetPS (hwnd); 


/*** Load the bitmap. 




HBitmap = GpiLoadBitmap 
(HPresSpace, 

NULL, 

ID_BITMAP, 

OL, 

OL) 7 


/* Handle to presentation space. */ 
/* Resource module handle: EXE file. */ 
/* Identifier of bitmap resource. */ 
/* Width to stretch bitmap: no stretch. */ 
/* Height to stretch bitmap: no stretch. */ 


/*** Release the presentation space. *****************************************/ 
WiriReleasePS (HPresSpace) ? 
return FALSE; 

} /* end Create */ 

MRESULT EXPENTRY Destroy (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/*** Remove the bitmap resource from memory. *********************************/ 


GpiDeleteBitmap 
(HBitmap); 

return FALSE; 

} /* end Destroy */ 


/* Bitmap handle. 


MRESULT EXPENTRY Paint (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


HPS HPresSpace; 
RECTL Rect; 


/* Presentation space handle. */ 

/* Window rectangle, in window coordinates. */ 


HPresSpace = WinBeginPaint /* Returns presentation space handle, 
(hwnd, /* Window handle. 


@ Figure 10.19: 

An application that loads and displays a bitmap (continued) 
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0/ /* 0 requests a cache presentation space. */ 

0)? /* Address of variable to set to invalid region: none.*/ 

WinQueryWindowRect /* Obtain coordinates of client window. */ 

(hwnd, /* Window handle. */ 

&Rect); /* Structure to receive coordinates. */ 

/*** Draw the bitmap. ********************************************************/ 


WinDrawBitmap 

(HPresSpace, 

HBitmap, 

NULL, 

(PPOINTL)&Rect, 
CLR_NEUTRAL, 
CLR_BACKGROUND, 
DBM_STRETCH)? 

WinEndPaint (HPresSpace) 

return FALSE; 

} /* end Paint */ 


/* Presentation space handle. */ 

/* Bitmap handle from GpiLoadBitmap. */ 

/* Section of bitmap to draw: NULL = ALL.*/ 

/* Pointer to rectangle to fill. */ 

/* Foreground color: system default. */ 

/* Background color: system default. */ 

/* Flag: fill rectangle with bitmap. */ 

/* Tells Presentation Manager that */ 

/* redrawing is complete. */ 


® Figure 10.19: 

An application that loads and displays a bitmap (continued) 

displayed by the example application of Figure 10.19 uses 50 x 50 pixels, 
and it is shown within the Icon Editor in Figure 10.20. 

When you save a bitmap file, the system will assign it the .BMP ex¬ 
tension. The next step is to define the bitmap in the resource script. Bit¬ 
maps are defined following the BITMAP keyword; the example 
resource script in Figure 10.17 defines a bitmap using the following line: 


BITMAP ID BITMAP FIG10 19.BMP 


This example assumes that the bitmap designed in the Icon Editor was 
saved under the name FIG10_19.BMP. Note that the identifier IDJBIT- 
MAP, which is defined in the header file of Figure 10.18, will be used to 
refer to the bitmap within the C source code of Figure 10.19. 
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• Figure 10.20: 

The example bitmap within the Icon Editor 


Once the bitmap data have been placed in a resource segment within 
the executable file, you can display the bitmap within the client win¬ 
dow by performing the following function calls: 

• Call GpiLoadBitmap (Figure 10.21) to load the bitmap from the 
resource segment into memory. When you call this function, you 
must have a valid handle to a presentation space. 

e Call WinDrawBItmap (Figure 10.22) to display the bitmap 

within the client window. You must also have a valid handle to a 
presentation space when calling this function. 

® When you have completed displaying the bitmap, call Gpi- 

OeleteBitmap (Figure 10.23) to release the bitmap from memory. 

The overall structure of the bitmap demonstration program of Figure 
10.19 is quite similar to that of the icon demonstration program of Figure 
10.6. In both programs, the resource is loaded in response to the WMCRE- 
ATE message, it is displayed during processing of the WM_PAINT mes¬ 
sage, and it is released upon receipt of the WM_DESTROY message. The 
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WM_CREATE message is processed by the function Create, which 
loads the bitmap using the following instructions: 

HPS HPresSpace; 

HPresSpace = WinGetPS (hwnd); 


HBitmap - GpiLoadBitmap 

(HPresSpace, /* Handle to presentation space. */ 

NULL, /* Resource module handle: .EXE file.*/ 

ID__BITMAP, /* Identifier of bitmap resource. */ 

0L, /* Width to stretch bitmap: */ 

/* no stretch. */ 

0L); /* Height to stretch bitmap: */ 

/* no stretch. */ 


WinReleasePS (HPresSpace); 

Note that unlike the function WinLoadPointer, which loads an icon or 
pointer, the function GpiLoadBitmap requires a handle to a presenta¬ 
tion space. If possible, the system will store the bitmap data within 
memory provided by the device associated with this presentation space 
(which, in this case, is the video display device). Note that the identifier, 
ID_BITMAP, passed as the third parameter, is the same value assigned 
to the bitmap by the BITMAP definition in the resource script. The 
fourth and fifth parameters to this function allow you to adjust the size 
of the bitmap as it is loaded; specifically, the fourth parameter gives the 
number of horizontal pixels and the fifth parameter the number of ver¬ 
tical pixels. If either of these two parameters contains a nonzero value, 
the system will adjust the bitmap as it is copied into memory to contain 
the requested number of horizontal or vertical pixels; if either of these 
values is zero, the system will preserve the original number of pixels in 
the corresponding direction. The example application assigns a value of 
0 to both parameters; therefore, the bitmap retains the number of pixels 
assigned when it was created in the Icon Editor (which was 50 x 50). 
Note, however, that the size of the bitmap will be adjusted when it is 
actually displayed in the client window. 
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GpiLoadBitmap 

Purpose: 

Loads a bitmap from a resource segment into memory. 
Prototype: 

HBITMAP APIENTRY 
(HPS hps, 

USHORT hModule, 


USHORT idBitmap, 
LONG 1Width, 


LONG lHeight); 


Return Value: 

The handle of the bitmap in memory, or the value 
GPI_ERROR if an error occurred. 


® Figure 10.21: 

The GpiLoadBitmap Presentation Manager function 


GpiLoadBitmap 

Handle to a presentation space. 
Resource module handle; if the 
resource is contained within the 
executable file, this parameter must be 
assigned NULL; if the resource is in a 
dynamic-link module, the parameter 
must contain the module handle 
returned by DosLoadModule. 

The identifier assigned to the bitmap 
within the resource file. 

The width in pixels to be given the 
bitmap when it is copied into memory; 
if 0, the bitmap is given its original 
width. 

The height in pixels to be given the 
bitmap when it is copied into memory; 
if 0, the bitmap is given its original 
height. 
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Purpose: 

Draws a bitmap within the specified presentation space. 

Prototype: 

BOOL APIENTRY WinDrawBitmap 

(hps hpsDst, Handle of the presentation space in 

which the image is to be drawn. 

hbitmap hbm, Handle of the bitmap to be drawn. 

prectl pwrcSrc, Pointer to a RECTL structure (defined 

in Figure 2.22) containing the 
coordinates of the portion of the 
bitmap that is to be drawn; if this 
parameter is NULL, the entire bitmap 
is drawn. 

ppointl pptlDst , Pointer to a POINTL structure (defined 

in Figure 3.28) containing the 
coordinates of the point within the 
presentation space where the lower 
left corner of the bitmap is to be 
placed; if, however, the fs flag 
parameter contains the switch 
DBM_STRETCH, this parameter 
should point to a RECTL structure 
containing the coordinates of the 
rectangle that is to be filled with the 
bitmap. 

long clrFore, Foreground color to be used for 

drawing the bitmap. 

long cirBack, Background color to be used for 

drawing the bitmap. 

Figure 1022: 

The WinDrawBitmap Presentation Manager function 




ushort fs) ; Flags that specify how the bitmap is to 

be drawn; you can choose from the 
following values: 

Value Effect 

DBM_NORMAL Bitmap drawn 

normally 

DBM_INVERT Bitmap colors 

inverted 

DBM_HALFTONE Bitmap drawn with a 
halftone pattern 

DBM_STRETCH Bitmap is stretched to 

fill the rectangle 
specified by the 
pptlDst parameter, 
which must point to a 
RECTL structure 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Figure 10.22: 

The WinDrawBitmap Presentation Manager function (continued) 


GpiDeleteBitmap 

Purpose: 

Frees a bitmap. 

Prototype: 

BOOL APIENTRY GpiDeleteBitmap 

(hbitmap hbm) ; Handle of bitmap to be freed. 
• Figure 10.23: 

The GpiDeleteBitmap Presentation Manager function 
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Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

When a process calls this function, it relinquishes its access to 
the specified bitmap; the bitmap is not actually deleted until 
all processes holding handles to the bitmap have called this 
function. 


• Figure 10.23: 

The GpiDeleteBitmap Presentation Manager function (continued) 

The WM DESTROY message is sent when the window is destroyed, 
and is processed by the function Destroy. This function removes the bit¬ 
map from memory through the following function call: 

GpiDeleteBitmap 
(HBitmap); 

The WM_PAINT message is processed in the function Paint. As in 
previous examples, this function obtains a handle to a presentation 
space by calling WinBeginPaint and releases this handle through Win- 
EndPaint. Also, as you have seen before, it calls WinQueryWindow- 
Rect to obtain the coordinates of the current window in the RECTL 
structure Rect. It then displays the bitmap through the following func¬ 
tion call: 


WinDrawBitmap 

(HPresSpace, /* Presentation space handle. */ 

HBitmap, /* Bitmap handle from */ 

/* GpiLoadBitmap. */ 

null, /* Section of bitmap to draw: 

/* NULL = ALL. */ 

(PPOINTL)&Rect, /* Pointer to rectangle to fill. */ 

CLR_NEUTRAL, /* Foreground color: */ 

/* system default. */ 

CLR_BACKGROUND, /* Background color: */ 
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/* system default. */ 

DBM_STKETCH); /* Flag: */ 

/* fill rectangle with bitmap. */ 

The third parameter to this function specifies the coordinates of the por¬ 
tion of the bitmap that is to be drawn; the value NULL causes the func¬ 
tion to display the entire bitmap. The last parameter passes the value 
DBM_STRETCH; this flag forces the function to adjust the size of the 
bitmap so that it fills the rectangular window area specified by 
the fourth parameter. Since the fourth parameter is given the dimen¬ 
sions of the client window obtained from WinQueryWindowRect, the 
bitmap always fills the entire client window. When the system displays 
the bitmap, it adds or subtracts pixels as necessary; as the user resizes 
the window, the overall size and proportions of the bitmap change ac¬ 
cordingly. Figure 10.24 illustrates the bitmap image displayed within 
the client window; compare this figure with Figure 10.20, which il¬ 
lustrates the bitmap as it was originally designed in the Icon Editor. 

Finally, the fifth and sixth parameters cause the bitmap to be drawn 
using the default system foreground and background colors described 



® Figure 10.24: 

The bitmap as displayed by the program of Figure 10.19 
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previously in the chapter (and listed in Figure 2.23). Note that unlike 
previous versions of this function. Paint does not bother to erase the 
client window because the bitmap data always fill the entire window. 


* OTHER RESOURCES 

This final section discusses two additional Presentation Manager 
resources: strings and programmer-defined resource types. 


Strings 

The Presentation Manager allows you to define a table of strings 
within the resource script. Like other resources, the string table is inserted 
into one or more resource segments within the executable file. The pro¬ 
gram can subsequently copy a string from this table into a program buffer, 
and it can display or otherwise process the contents of the string. 

You can place the collection of program error messages, the program 
name, or other constant string data within a string table rather than 
defining the strings within the C source code. Defining all constant 
strings within a string table is especially useful for applications that will 
be translated into foreign languages. When such a program is trans¬ 
lated, all strings, menu labels, and other language-specific items are 
conveniently located within the resource script rather than dispersed 
throughout the source code. Also, modifying the resource script does 
not require recompiling the program, typically the slowest step in 
building an application. 

In the example application of Figures 10.15 through 10.19, presented 
in the previous section, the program title is placed in a string table 
rather than defined in the C source code. When the program runs, it 
copies this string from the resource segment and passes it to the Win- 
CreateStdWindow function as the window title. 
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The first step is to define the string table in the resource script. The 
string table is labeled with the keyword STRINGTABLE as shown in the 
following example, which defines three strings: 

#define XD_STRINGONE 0 
#define ID_STRINGTWO 1 
#define ID__STRINGTHREE 2 


STRINGTABLE 

BEGIN 

ID STRXNGONE, "This is the first string" 

ID STRINGTWO, "This is the second string" 

ID STRXNGTHREE, "This is the third string" 

END 

The three string identifiers in this example, IDJ3TRINGONE, 
ID_STRINGTWO, and ID_STRINGTHREE, are given unique values 
and will be used to access the corresponding strings from the C pro¬ 
gram. All required strings must be placed in the same string table, since 
you can define only a single string table in a resource file. Each string 
has a maximum length of 255 characters. 

Note that the system places up to 16 strings within a single resource 
segment; if you define more than 16 strings in a given string table, the 
system uses additional resource segments as required. The system 
labels each resource segment based upon the identifiers of the strings 
contained in the segment, according to the following formula: 

resource_label = ( string_identif±er / 16) + 1 

Therefore, for example, a string with the identifier 0 is placed in re¬ 
source segment 1, and a string with the identifier 18 is placed in 
resource segment 2. Accordingly, to minimize the number of segments 
required, you should assign identifiers that are numbered consecutive¬ 
ly beginning with a multiple of 16 (as in the preceding example). 



WinLoadString 


Purpose: 


Loads a string from a string table resource into a program 

buffer. 


Prototype: 


SHORT APIENTRY 

WinLoadString 

(HAB hab, 

Anchor block handle. 

HMODULE hmod, 

Resource module handle; if the resource is 
contained within the executable file, this 
parameter must be assigned NULL; if the 
resource is in a dynamic-link module, the 
parameter must contain the module handle 
returned by DosLoadModule. 

USHORT id, 

Identifier assigned to the string in the 
resource script. 

SHORT cchMax, 

Length of the receiving buffer. 

PSZ pchBuffer) ; 

The receiving buffer. 

Return Value: 


The length of the string copied (excluding the terminating 
NULL character; the maximum value is ccMax - 1). 

Notes: 


The function copies at most ccMax - 1 characters and ap¬ 
pends a NULL character to the end of the string in the receiv- 

ing buffer. 



© Figure 1025: 

The WinLoadString Presentation Manager function 


The example resource file given in Figure 10.17 defines a string table 
containing a single string as follows: 

STRXNGTABLE 

BEGIN 

ID_PROGNAME, "Bitmap Demo" 
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You can call the Presentation Manager function WinLoadString (Fig¬ 
ure 10.25) to copy a given string from the resource segment into a pro¬ 
gram buffer. The example application of Figure 10.19 calls this function 
to obtain the string containing the program title, immediately before 
calling WinCreateStdWindow. The function call is as follows: 


char ProgName [32]; 
WinLoadString 
(HAncBlk , 

NULL, 

XD__PROGNAME, 
sizeof (ProgName ), 
ProgName); 


/* Anchor block handle. */ 
/* Module handle: in .EXE file.*/ 
/* String identifier. */ 
/* size of receiving buffer. */ 
/* Receiving buffer. */ 


Note that you do not have to explicitly release a string resource, unlike 
the other resources described in this chapter, since it is loaded into a 
private program buffer rather than into a memory segment maintained 
by the system. 


Programmer-Defined Resource Types 

In addition to resources belonging to the predefined resource types 
discussed in this book, the Presentation Manager allows you to create 
resources belonging to a programmer-defined type. These resources per¬ 
mit you to insert data of an arbitrary format into resource segments m 
the program file. Such resources are declared in a resource script using 
the following syntax: 

RESOURCE type_id name_±d resource__fHe 

RESOURCE is the keyword that signifies a programmer-defined 
resource type; typejd is the resource type identifier; mrnejd is the re¬ 
source name identifier; and resource Jile is the name of the file that con¬ 
tains the resource data. 

Note that all resource types have an associated resource type iden¬ 
tifier; you do not normally need to include the type identifier when 
declaring a resource belonging to a predefined type because the type is 
implicit in the keyword that begins the definition. For example, the 
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keyword BITMAP implies a bitmap type resource, and you therefore do 
not need to specify the type identifier (which is RT_BITMAP). When 
creating a resource belonging to a programmer-defined type, however, 
you must include a resource type identifier; as you will see, this iden¬ 
tifier is subsequently used when the program accesses the resource. The 
resource type identifier must be a value greater than 255. 

The resource namejd is analogous to the identifiers that are specified 
when you declare resources belonging to predefined types such as bit¬ 
maps. This identifier is also required when accessing the resource from 
the program. There can be several resources of the same type, provided 
that the names are unique; likewise, there can be several resources that 
have the same name as long as the types are unique. In other words, the 
combination of name and type must be unique for each resource. 

Finally, the file specified in the declaration supplies the actual resource 
data; this file can contain textual or binary data in any format that can be 
understood by the application. The file could, for example, contain the text 
required to implement a help utility. The following is an example of the 
definition of a resource that has a programmer-defined resource type: 

#define ID_MYTYPE 256 
#define ID_HELPTEXT 1 

RESOURCE ID_MYTYPE ID_HELPTEXT HELP.TXT 

In this example, the file HELP.TXT could be a file containing the text 
that is displayed by a help utility. 

To access the data belonging to a programmer-defined resource type 
from your program, you must call the OS/2 kernel function DosGet- 
Resource, which returns a selector to the segment containing the 
resource data. This segment contains exactly the same data stored in the 
file specified in the resource script. For example, the following call ob¬ 
tains a selector that can be used to access the resource declared in the 
previous example: 


SEL SelRes; 


/* Selector to memory segment 
/* containing resource. 


*/ 

*/ 
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DosGetResource 


(NULL, 

/* 

Module handle: 

*/ 


/* 

NULL means the .EXE file. 

*/ 

ID_MYTYPE, 

/* 

Resource type identifier. 

*/ 

ID HELPTEXT, 

/* 

Resource name identifier. 

*/ 

&SelRes); 

/* 

Address to receive resource 

*/ 


/* 

selector. 

*/ 


DosGetResource 


Purpose: 


Loads the specified resource segment into memory. 

Prototype: 


USHORT APIENTRY 

DosGetResource 

(HMODULE hmod, 

Resource module handle; if the resource is 
contained within the executable file, this 


parameter must be assigned NULL; if the 
resource is in a dynamic-link module, the 
parameter must contain the module handle 
returned by DosLoadModule. 

USHORT idType, 

The resource type identifier. 

USHORT idName, 

The resource name identifier. 

PSEL psel); 

Address of variable to receive the selector of 
the memory segment containing the resource. 

Return Value: 


0 if the function is successful, otherwise one of the following 

error codes: 


ERROR_INVALID_MODULE 

ERROR_INVALID_SELECTOR 

ERROR_CANT_FIND_RESOURCE 


© Figure 10.26: 

The DosGetResource OS/2 kernel function 
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Once you have obtained a selector to the segment containing the 
resource data, you can use this selector to construct a far pointer to ad¬ 
dress the individual data items. For example, the following code con¬ 
structs a character pointer, PtrHelpText, which can be used to read the 
individual characters of the help text: 

PCH PtrHelpText; /* Far character pointer to */ 

/* resource data. */ 


PtrHelpText = MAKEP (SelRes,0); /* Construct far*/ 

/* pointer. */ 

Note that the program is free to read or copy the data in the resource 
segment, but must not attempt to write to this segment, since it is desig¬ 
nated as read-only (attempting a write operation would cause a protec¬ 
tion violation). Also, you must be careful not to try to address beyond 
the end of the resource segment (which would also cause a protection 
violation). Fortunately, you can obtain the length of the segment in 
bytes by calling the OS/2 kernel function DosSizeSeg (Figure 10.27), as 
follows: 

ULONG SegSize; /* Size of resource segment. */ 


SegSize — DosSizeSeg /* Obtain segment size. */ 

(SelRes, /* Selector from DosGetResource. */ 

&SegSize); /* Receives segment size. */ 

Note also that programmer-defined resource types are manipulated 
using basic OS/2 kernel function calls. Accordingly, these resource 
types are available not only to Presentation Manager applications, but 
also to other OS/2 protected mode programs. 
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DosSizeSeg 

Purpose: 

Obtains the size in bytes of a memory segment. 


Prototype: 


USHORT APIENTRY DosSizeSeg 


(SEL sel); 

PULONG pulSize); 


Selector of the segment. 

Pointer to the variable to receive the 
size in bytes of the segment specified 
by the parameter sel. 


Return Value: 

Zero if the function was successful, or a nonzero error code if 
the function failed. 


® Figure 1027: 

The DosSizeSeg OS/2 kernel function 









A lthough the Presentation Manager does not require a 
mouse, installing and using a mouse greatly simplifies 
managing objects on the screen and issuing system and 
program commands. The Presentation Manager auto¬ 
matically provides a mouse interface for the objects that it manages, 
such as title bars, sizing frames, maximize and minimize boxes, menus, 
and scroll bars. Accordingly, you can use the mouse to perform such 
tasks as switching among applications, moving or adjusting the size 
and shape of a window, issuing menu commands, and scrolling data 
within a window. Presentation Manager applications gain the advan¬ 
tage of this system mouse interface without any explicit programming. 

This chapter describes how you can extend this default mouse inter¬ 
face by calling system functions and processing system messages that 
allow you to control the mouse pointer and to act upon specific mouse 
events. Most commonly, an application uses these facilities to manage 
the mouse while the pointer is located within the client window. There¬ 
fore, just as a program typically reads the keyboard while the client 
window has the input focus, it can also explicitly handle the mouse 
while the pointer is within the client window boundaries. 

Note that the system automatically displays the mouse pointer on 
the screen and moves the pointer image as the user moves the mouse 
on the desk surface. An application is typically concerned with three 
mouse parameters: the location of the mouse pointer within the win¬ 
dow, the shape of the mouse pointer, and the status of the mouse but¬ 
tons. This chapter discusses each of these three basic parameters; the last 
section then describes how to use these facilities to implement a stand¬ 
ard mouse interface. 


FINDING THE 

. MOUSE POINTER LOCATION 

Before your program calls a Presentation Manager function to 
determine the mouse location or perform other explicit operations on 
the mouse, it can call the WinQuerySysValue function to determine 
whether a mouse is installed. This function, described in Figure 11.1, 
can be called to determine any one of a large number of system values. 
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You request a specific system value through the second parameter 
(SHORT lSysValue), and WinQuerySysValue returns this value direct- 
ly to the calling program. A list of identifiers for the possible system 
values is given in Table 11.1; note that WinQuerySys Value supplies 
dimension values in pixel units and time values in milliseconds. To 
determine whether the mouse is installed, you pass the identifier 
SV_MOUSEPRESENT, and WinQuerySys Value returns TRUE if a 
mouse is installed or FALSE if there is no mouse. The example program 


WinQuerySys Value 

Purpose: 

Returns the specified system value. 

Prototype: 

LONG APIENTRY WinQuerySysValue 

(HWND hwndDesktop, The value HWND_DESKTOP to 
identify the desktop window. 

short lSysValue) ; The identifier of the desired system 
value; the constants for these 
identifiers have the SV_ prefix and are 
listed in Table 11.1. 

Return Value: 

The requested system value, or 0 if an error occurred. 

Notes: 

Some of the system values can be set through the function 
WinSetSystemValue. 

Related Functions: 

WinSetSystemValue 


® Figure 11.1: 

The WinQuerySys Value Presentation Manager function 
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listed in Figure 11.14 and described in the next section tests whether a 
mouse is present, as follows: 

if (!WinQuerySysValue 
(HWND_DESKTOP, 

SV_MOUSEPRESENT)) 

ErrorQuit ("Program requires mouse"); 

A window procedure can determine the position of the mouse 
pointer within its window using one of two basic methods. First, it 
can call the WinQueryPointerPos function (Figure 11.2) or the Wm- 
QueryMsgPos function (Figure 11.3) to obtain the pointer position at 
any time it requires this information. Alternatively, it can process the 
WM_MOUSEMOVE message, which is sent to the client window pro¬ 
cedure each time the position of the pointer changes and the pointer is 
located within the client window. 

WinQueryPointerPos returns the current position of the mouse in 
screen coordinates ; screen coordinates are the horizontal and vertical posi¬ 
tions of the mouse relative to the lower left corner of the desktop win¬ 
dow (the entire screen). You can convert screen coordinates mto 
coordinates relative to a specific window by calling the WinMap- 
WindowPoints Presentation Manager function (Figure 11.4). It is general¬ 
ly easiest to work with coordinates that are relative to the client window. 
As an example, the following code obtains the current screen coordinates 
of the mouse pointer and then converts these values into coordinates rela¬ 
tive to the client window: 

HWND HClient; 

POINTL MousePosition; 


WinQueryPointerPos 
(HWND_DESKTOP, 
&MousePosition); 


/* Desktop window handle. */ 

/* Address of POINTL structure. */ 


WinMapWindowPoints 
(HWND_DESKTOP , 
HClient, 


/* Existing coordinate space. 
/* Desired coordinate space. 


*/ 

*/ 
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SMousePosition, /* Address of POINTL array. */ 

' /* Only one element in array. */ 

This example assumes that the variable HClient contains the client win¬ 
dow handle (returned by WinCreateStdWindow). After the call to Win- 
Map WindowPoints, the structure MousePosition contains the current 
position of the mouse in pixel units, relative to the lower left corner of 
the client window. Conveniently, this position is specified in the same 
units and is relative to the same coordinate system that has been used 
when calling such functions as GpiCharStringAt, WinlnvalidateRect, 
and WinDrawBitmap in previous examples in the book. 


• Table 11.1: System Value Identifiers 


Identifier 

Value 

System Value 

*SV_SWAPBUTTON 

0 

Flag indicating whether 
mouse buttons are 
swapped 

*SV_DBLCLKTIME 

1 

Mouse double-click time 

*SV_CXDBLCLK 

2 

Width of mouse double¬ 
click sensitive area 

*SV_CYDBLCLK 

3 

Height of mouse double¬ 
click sensitive area 

SV_CXSIZEBORDER 

4 

Width of sizing border 

SV_C Y SIZEBORDER 

5 

Height of sizing border 

*SV_ALARM 

6 

Flag indicating whether 
alarm sound generated 
by Win Alarm (Figure 

6.9) is enabled 

*SV_CURSORRATE 

9 

Cursor blink rate 

SV_FIRSTSCROLLRATE 

10 

Delay before autoscroll¬ 
ing starts when using a 
scroll bar 

SV_SCROLLRATE 

11 

Delay between scroll 
operations when using a 
scroll bar 
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® Table 11.1: System Value Identifiers (continued) 


Identifier 


Value System Value 


SV NUMBEREDLISTS 12 


*SVJWARNINGFREQ 13 


*SV_NOTEFREQ 


*SV_ERRORFREQ 


*SV WARNINGDURATION 16 


*SV NOTEDURATION 17 


*SV ERRORDURATION 18 


SV_CXSCREEN 
SV CYSCREEN 


Flag indicating whether 
the system automatically 
numbers selection lists 
such as pull-down 
menus and groups of 
radio buttons 

Frequency of sound 
generated by passing 
WinAlarm (Figure 6.9) 
the WA_WARNING flag 

Frequency of sound 
generated by passing 
WinAlarm (Figure 6.9) 
the WA_NOTE flag 

Frequency of sound 
generated by passing 
WinAlarm (Figure 6.9) 
the WAJERROR flag 

Duration of sound 
generated by passing 
WinAlarm (Figure 6.9) 
the WA_WARNING flag 

Duration of sound 
generated by passing 
WinAlarm (Figure 6.9) 
the WA_NOTE flag 

Duration of sound 
generated by passing 
WinAlarm (Figure 6.9) 
the WAJERROR flag 

Width of screen 
Height of screen 
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• Table 11 . 1 : System Value Identifiers (continued) 


Identifier 

Value 

System Value 

S V_CX V SCROLL 

22 

Width of vertical scroll 
bar 

SV_CYHSCROLL 

23 

Height of horizontal 
scroll bar 

S V_C YV SCROLLARRO W 

24 

Height of vertical scroll 
bar arrow 

SV_CXHSCROLLARROW 

25 

Width of horizontal 
scroll bar arrow 

SV_CXBORDER 

26 

Width of normal win¬ 
dow border 

SV_CYBORDER 

27 

Height of normal win¬ 
dow border 

SV_CXDLGFRAME 

28 

Width of dialog box 
border 

SV_CYDLGFRAME 

29 

Height dialog box border 

SV_CYTITLEBAR 

30 

Height of title bar 

SV_CYVSLIDER 

31 

Height of vertical scroll 
bar slider 

SVCXHSLIDER 

32 

Width of horizontal 
scroll bar slider 

SV_CXMINMAXBUTTON 

33 

Width of minimize/maxi¬ 
mize button 

SV_CYMINMAXBUTTON 

34 

Height of minimize/max¬ 
imize button 

SV_CYMENU 

35 

Height of menu bar 

SV_CXFULLSCREEN 

36 

Width of client window 
when window is maxi¬ 
mized 

SV_CYFULLSCREEN 

37 

Height of client window 
when window is maxi¬ 
mized 
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« Table 11.1: SystemJ/a^^ 


Identifier 

Value 

System Value 

SV_CXICON 

38 

Width of icon 

SV_CYICON 

39 

Height of icon 

SV_CXPOINTER 

40 

Width of pointer 

SV_CYPOINTER 

41 

Height of pointer 

SV_DEBUG 

42 

Flag indicating debug 
version 

SV_CMOUSEBUTTONS 

43 

Number of mouse but¬ 
tons (0 if no mouse is 
installed) 

SV_POINTERLEVEL 

44 

Pointer hide level (0 is 
visible) 

SV_CURSORLEVEL 

45 

Cursor hide level (0 is 
visible) 

SV_TRACKRECTLEVEL 

46 

Tracking rectangle hide 
level (0 is visible) 

SV_CTIMERS 

47 

Number of available 
timers 

SV_MOUSEPRESENT 

48 

Flag indicating whether 
mouse is installed 

* Marks value that can he set through WinSetSysValue 


Note that the coordinates used to specify the mouse pointer position 
are actually the coordinates of a single pixel within the pointer known 
as the hot spot. The hot spot within the standard arrow pointer, for ex¬ 
ample, is the pixel at the tip of the arrow. As mentioned in Chapter 10, 
you must designate the hot spot when designing a custom pointer 
using the Icon Editor. 

The function WinQueryMsgPos also returns the position of the 
mouse pointer in screen coordinates. This function, however, does not 
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WinQueryPointerPos 

Purpose: 

Obtains the current position of the mouse pointer in screen 
coordinates. 

Prototype: 

BOOL APIENTRY WinQueryPointerPos 
(hwnd hwndDesktop , The value HWND_DESKTOP to 
identify the desktop window. 

ppointl ppti) ; Pointer to a POINTL structure (defined 

in Figure 3.28) that is assigned the 
current coordinates of the mouse 
pointer hot spot in screen coordinates. 

Return Value: 

TRUE if the function is successful, or FALSE if an error 
occurred. 

Notes: 

This function gives the horizontal and vertical position of the 
mouse relative to the lower left corner of the screen ; to con¬ 
vert these values to coordinates relative to the lower left 
corner of a given window , you can call WinMapWindow- 
Points. You can call WinSetPointerPos to set the current 
position of the pointer. 

Related Functions: 

WinMapWindowPoints (Figure 11.4) 

WinQueryMsgPos (Figure 11.3) 

WinSetPointerPos (Figure 11.11) 


• Figure 11.2: 

The WinQueryPointerPos Presentation Manager function 
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WinQueryMsgPos 

Purpose: 

Obtains the position of the mouse pointer at the time the last 
message extracted from the message queue was posted. The 
position is given in screen coordinates. 

Prototype: 

BOOL APIENTRY WinQueryMsgPos 

(hab hab , Anchor block handle. 

PPOINTL pptl) ; Pointer to a POINTL structure (defined in 
Figure 3.28) that is assigned the coordinates 
of the mouse pointer hot spot. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

To obtain the current pointer position, call the function Win- 
QueryPointerPos. WinQueryMsgPos gives the horizontal 
and vertical position of the mouse relative to the lower left 
corner of the screen; to convert these values to coordinates 
relative to the lower left corner of a given window , you can 
call WinMapWindowPoints. 

Related Functions: 

WinMapWindowPoints (Figure 11.4) 

WinQueryPointerPos (Figure 11.2) 

m Figure 11.3: 

The WinQueryMsgPos Presentation Manager function 
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WinMapWindowPoints 

Purpose: 

Maps the coordinates of one or more points from the coor¬ 
dinate space relative to one window into the coordinate 
space relative to another window 


Prototype: 


BOOL APIENTRY WinMapWindowPoints 


(HWND hwndFrom, 


HWND hwndTo, 


PPOINTL pptl, 


SHORT cwpt); 


Handle of the window from whose 
coordinate space the coordinates of the 
points are to be mapped; the value 
HWND_DESKTOP indicates that the points 
are given in screen coordinates. 

Handle of the window to whose coordinate 
space the coordinates of the points are to be 
mapped; the value HWND_DESKTOP 
indicates that the points are to be converted 
into screen coordinates. 

Pointer to an array of POINTL structures 
(defined in Figure 3.28) containing the 
coordinates of the points that are to be 
mapped. 

The number of POINTL structures in the 
array pointed to by the pptl parameter. 


Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 


Notes: 

Since a RECTL structure (defined in Figure 2.22) is equi¬ 
valent to two contiguous POINTL structures, you can con¬ 
vert the coordinates contained in a RECTL structure by 
setting pptl to the address of this structure and assigning 
cwpt a value of 2. 


© Figure 11.4: 

The WinMapWindowPoints Presentation Manager function 
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return the current position; rather, it returns the position of the pointer at 
the time the last message obtained from the message queue was posted. 
Remember from Chapter 2 (in the section entitled Get and Dispatch Mes¬ 
sages) that all messages in the message queue contain the position of 
the mouse at the time the message was posted (the mouse position is the 
sixth and last field of the QMSG structure). When your program calls 
WinDispatchMsg to dispatch a message, the system calls the ap¬ 
propriate window procedure, but does not pass this procedure the 
mouse position (it passes only the first four fields of QMSG). By calling 
WinQueryMsgPos, however, the window procedure can obtain this 
position. 

The second basic method for the window procedure to obtain the 
mouse position is by processing the WM_MOUSEMOVE message (Fig¬ 
ure 11.5). This message is sent whenever the mouse position changes, 
and it is accompanied by the new coordinates of the mouse position. 
Note that WM_MOUSEMOVE is normally sent only to the window 
directly below the mouse pointer (unless a window procedure has 
called WinSetCapture, which forces the system to send all subsequent 
mouse messages to the specified window regardless of the location of 
the pointer). Note also that the coordinates supplied by this message are 
relative to the receiving window, and therefore they do not have to be 
remapped from screen coordinates. The example programs given in the 
following two sections illustrate the use of the WM_MOUSEMOVE 
message. 

The choice of basic methods for obtaining the mouse pointer posi¬ 
tion—calling a function or processing a message—depends upon the 
requirements of the application. Calling WinQueryPointerPos provides 
the most current position value (the window procedure cannot receive ad¬ 
ditional WM_MOUSEMOVE messages until it finishes processing the cur¬ 
rent message; if the user is moving the mouse while a message is being 
processed, the value supplied by the last WM_MOUSEMOVE message 
may no longer be valid). Obtaining the mouse position by processing the 
WMJVfOUSEMOVE message, however, has several advantages. First, this 
method is more in conformance with the message-based architecture of a 
Presentation Manager application, and it frees the program from having to 
explicitly poll the system for the mouse position. Also, the coordinates 
provided by this message are already relative to the client window, and 
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therefore do not have to be remapped. Finally, as you will see in the ex¬ 
ample programs in the following sections, this message provides a con¬ 
venient signal indicating that the mouse pointer is currently located 
within the client window. 


WM_MOUSEMOVE 


Purpose: 


This message is sent by the system to the window beneath 

the mouse pointer (or to the mouse capture window, if any) 
each time the position of the mouse pointer changes. 

Parameters: 


MPARAM mpl 


low-order word: 

The horizontal pointer coordinate 
relative to the lower left corner of the 
window. 

high-order word: 

The vertical pointer coordinate relative 
to the lower left corner of the window. 

MPARAM mp2 


low-order word: 

The result returned from a 

WM_HITTEST message, or 0 if a 
mouse capture is in progress. 

high-order word: 

0. 

Return Value: 


The window procedure should return TRUE if it has 
processed the message, or FALSE if it has not processed the 

message. 



• Figure 11.5: 

The WM_MOUSEMOVE Presentation Manager message 
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SETTING THE 

. MOUSE POINTER SHAPE 

The default mouse pointer automatically displayed by the system 
is the standard single-headed, slanted arrow. You can force the sys¬ 
tem to display an alternative pointer by calling the Presentation 
Manager function WinSetPointer (Figure 11.6). Once you call this func¬ 
tion, passing it the handle of the desired pointer, the system uses this 
pointer until the function is subsequently called to specify another 
pointer. 

When you call WinSetPointer you can specify the handle of a pointer 
provided by the system, or the handle of a custom pointer that you have 
created using the Icon Editor. To obtain the handle of one of the pointers 
provided by the system, you can call the Presentation Manager function 
WinQuerySysPointer (Figure 11.7), passing the identifier of the desired 


WinSetPointer 

Purpose: 

Sets the mouse pointer that is displayed by the system. 
Prototype: 

BOOL APIENTRY WinSetPointer 
(hwnd hwndDesktop , The desktop window handle, 
HWND_DESKTOP. 

hpointer hptrNew) ; The handle of the new pointer; if this 
value is NULL, the pointer is removed 
from the screen. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

• Figure 11.6: 

The WinSetPointer Presentation Manager function 
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pointer as the second parameter. Note that the identifiers listed in Fig¬ 
ure 11.7 include eight standard mouse pointers as well as five standard 
icons. The system mouse pointers are illustrated in Figure 11.8, and the 
system icons are illustrated in Figure 11.9 (both the icons and the 
pointers are labeled in these figures using the identifiers that are passed 
to WinQuerySysPointer). Since the data structure for a pointer is the 
same as that for an icon, you could easily pass one of the system icon 
handles to WinSetPointer to install the icon as the current mouse 
pointer. However, the icons make rather awkward-looking pointers, 
and they are best displayed as stationary objects within the client win¬ 
dow using the WinDrawPointer function (Figure 10.9). The example 
program in Figure 11.14, explained later in this section, displays each of 
the standard system pointers. 


WinQuerySysPointer 


Purpose: 


Returns the handle to the requested system pointer or icon. 

Prototype: 


HPOINTER APIENTRY WinQuerySysPointer 

(hwnd hwndDesktop , The value HWND DESKTOP to 

identify the desktop window. 

short iptr , Identifier of the system pointer 

desired; you can choose from the 

following list: 


Identifier 

Pointer/Icon 

SPTR_ ARROW 

Standard arrow 
pointer 

SPTR_TEXT 

I-beam pointer 

SPTR_WAIT 

Hourglass pointer 

SPTR_MOVE 

Move pointer 

SPTR_SIZENWSE 

Double-headed 


arrow, sloping from 
upper left to lower 
right 


® Figure 11.7: 

The WinQuerySysPointer Presentation Manager function 
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SPTRJ3IZENESW 

Double-headed 
arrow, sloping from 
upper right to lower 
left 

SPTR_SIZEWE 

Horizontal 

double-headed arrow 

SPTRJ3IZENS 

Vertical 

double-headed arrow 

SPTRAPPICON 

Standard application 


icon 

SPTR_HANDICON 

Hand icon 

SPTR_QUESICON 

Question-mark icon 

SPTR_BANGICON 

Exclamation-mark 


icon 

SPTR_NOTEICON 

Asterisk icon 


bool f Load) / If this parameter is TRUE, the function 

creates a new copy of the system 
pointer and returns the handle to this 
copy; if the parameter is FALSE, the 
function returns the handle to the 
system pointer itself. 

Return Value: 

The pointer handle. 

Notes: 

If you assign fLoad a value of TRUE, you will obtain a new 
copy of the system pointer; you should select this option if 
you need to modify the pointer. If you assign FALSE to 
fLoad, you will obtain a handle to the system's copy of the 
pointer; note that an attempt to display this pointer (through 
WinSetPointer, for example) will fail if another process is 
currently accessing the same pointer. 

Related Functions: 

WinSetPointer (Figure 11.6) 


• Figure 11.7: 

The WinQuerySysPointer Presentation Manager function (continued) 
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Alternatively, you can pass WinSetPointer the handle of a custom 
pointer that you have created in the Icon Editor, converted into a pro¬ 
gram resource, and then loaded using the WinLoadPointer Presenta¬ 
tion Manager function. The techniques for designing a custom pointer 
were described in Chapter 10, in the section entitled Designing a Mouse 
Pointer. Also, these techniques are illustrated by the example program 
of Figure 11.21, which installs a custom mouse pointer and is described 
later in the chapter. 
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® Figure 11.8: 

The system mouse pointers 



® Figure 11.9: 

The system icons 
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Note that when your application has completed displaying a mouse 
pointer (either a system pointer or one you have created), you can 
release the pointer handle by calling WinDestroyPointer (Figure 10.10). 

Now that you have seen how to set the mouse pointer displayed by 
the system, the next question is when to display a specific pointer. Typi¬ 
cally, an application will set the mouse pointer according to one of two 
criteria. First, a program may select a mouse pointer according to the 
current position of the pointer. The simplest example is an application 
that selects a certain mouse pointer whenever the pointer is located 
within the client window. The example application in Figure 11.21 
(described in the section on Reading the Mouse Buttons) sets the mouse 
pointer to a custom pointer (a paintbrush created in the Icon Editor) 
whenever the pointer is located within the client window. This task is 
performed by simply calling the WinSetPointer function each time the 
WM_MOUSEMOVE message is received, as follows: 

HPOINTER HMousePtr; 


case WM MOUSEMOVE: 


WinSetPointer 

(HWNDJDESKTOP, 

HMousePtr) ; 

As you will see later in the chapter, HMousePtr contains the handle 
of the custom mouse returned by WinLoadPointer. The WM_MOUSE- 
MOVE message is sent to the client window when the mouse pointer 
first enters the window, and subsequently each time the pointer moves 
within the window. When the pointer leaves the client window, these 
messages are sent to the new underlying window, which presumably 
sets the pointer to another appropriate shape. It may seem inefficient to 
continually reset the pointer to the same value as it moves to various 
positions within the client window; however, the Microsoft documenta¬ 
tion indicates that this function is very fast when the specified pointer is 
the same as the current pointer. (Unfortunately, the system does not 
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provide messages that are sent only when the mouse enters or leaves 
the client window.) 

An application can also set the pointer to various shapes depending 
upon the specific position of the mouse pointer within the client win¬ 
dow. For example, an application might display the I-beam system 
pointer (identified by the value SPTR_TEXT) in a section of the client 
window containing text. To demonstrate this technique, the example 
program of Figure 11.14 displays one of the eight standard system 
pointers depending upon which section of the client window currently 
contains the mouse pointer. See the description of this program later in 
this section. 

A second possible criterion for selecting the mouse pointer shape is 
the current program activity. For example, while the program is execut¬ 
ing a lengthy operation, during which it cannot accept user input, it 
could display the hourglass system icon (identified by the value 
SPTR_WAIT). Also, a program currently engaged in moving an object 
might display the move icon (SPTR_MOVE, shown in Figure 11.8). 

Note that an application can display and move a mouse pointer even 
if a mouse is not installed. For example, in the absence of a mouse, a 
program might nevertheless display the hourglass mouse pointer to in¬ 
dicate a pause in input. Another example is a drawing program that 
uses the mouse pointer to indicate the drawing position; if a mouse 
were not installed, the program could still display the pointer, but 
would have to explicitly move the pointer in response to keyboard 
input. You can use the following steps to display and move a pointer in 
the absence of a mouse (the previous section in this chapter described 
how to determine whether a mouse is installed): 

• Call the function WinShowPointer (Figure 11.10) to cause the 
system to display the mouse pointer. (If a mouse is installed, the 
system automatically displays the pointer; if, however, a mouse 
is not installed, you can coax the system into displaying a 
pointer by calling WinShowPointer.) 
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WinShowPointer 

Purpose: 

Shows or hides the mouse pointer by changing the pointer 
hide level. 

Prototype: 

BOOL APIENTRY WinShowPointer 

(hwnd hwndDesktop , The value HWND_DESKTOP to 

identify the desktop window. 

BOOL f Show) ; If this value is TRUE, the function 

decrements the pointer hide level; if 
the value is FALSE, it increments the 
hide level. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

If the pointer hide level is 0, the mouse is displayed; if it is 
greater than 0, the mouse is hidden. If a mouse is installed, 
the system assigns the hide level an initial value of 0 (which 
shows the pointer); if no mouse is installed, the system as¬ 
signs an initial value of 1 (which hides the pointer). The hide 
level is not allowed to go below 0 (therefore, calling this 
function with fShow equal to TRUE when the mouse is al¬ 
ready visible has no effect). You can obtain the current hide 
level by calling WinQuerySysValue, passing an identifier of 
SVJPOINTERLEVEL as the second parameter. 

Related Functions: 

WinQuerySysValue (Figure 11.1) 


m Figure 11.10: 

The WinShowPointer Presentation Manager function 
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• Call WinSetPointerPos (Figure 11.11) to set the location of the 
pointer. (If a mouse is installed, the user and the system set the 
position of the pointer; if no mouse is installed, your program 
must explicitly set the position.) Note that in the same manner as 
WinQueryPointerPos, the location is specified in screen coor¬ 
dinates; you can call WinMapWindowPoints, if necessary, to 
generate screen coordinates from coordinates relative to the 
client window. 


WinSetPointerPos 

Purpose: 

Sets the position of the mouse pointer. 

Prototype: 

BOOL APIENTRY WinSetPointerPos 

(hwnd hwndDesktop , The value HWND DESKTOP to 
identify the desktop window. 

short x, The horizontal position of the pointer 

in screen coordinates. 

short y) ; The vertical position of the pointer in 

screen coordinates. 

Return Value: 

TRUE if the function was successful, or FALSE if an error occurred. 
Notes: 

The mouse position for this function, like the function Win¬ 
QueryPointerPos, is specified in screen coordinates (which 
are relative to the lower left corner of the screen). You can call 
WinMapWindowPoints to convert window relative coor¬ 
dinates to screen coordinates. 

Related Functions: 

WinMapWindowPoints (Figure 11.4) 

WinQueryPointerPos (Figure 11.2) 


• Figurell.il: 

The WinSetPointerPos Presentation Manager function 
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The example program in Figure 11.14 illustrates the techniques for 
obtaining a handle to a system pointer, and for assigning a pointer 
shape according to the current pointer position in the client window. 
Specifically, the program obtains a handle for each of the eight system 
mouse pointers illustrated in Figure 11.8. It then conceptually divides 
the client window into eight rectangles of approximately equal size; 
as the user moves the mouse pointer into each division, the program as¬ 
signs a different mouse pointer. For example, the normal arrow pointer 
is displayed when the pointer is in the lower left quadrant, and the I- 
beam pointer is displayed when the pointer is in the next quadrant, to 
the right in the bottom row. This program thus gives you an oppor¬ 
tunity to see each of the system pointers, one at a time. Figure 11.12 
provides a MAKE file for preparing this program, and Figure 11.13 con¬ 
tains the linker definition file. 


# Figure 11.12 

# This MAKE file prepares the program of Figure 11.14 

# 

FIG11_14.OBJ : FIG11_14.C 

cl /W2 /c /Zp /G2ws FIG11_14.C 

FIG11_14.EXE : FIG11_14.0BJ FIG11_13.DEF 

link /NOD FIG11_14.OBJ,, NUL, OS2.LIB SLIBCE.LIB, FIG11_13.DEF 


® Figure 11,12: 

A MAKE file for preparing the program of Figure 11.14 


; Figure 

2 

; Linker 

definition file for the program listed in Figure 3 

NAME 

FIG11 12 

PROTMODE 


HEAPSIZE 

1024 

STACKSIZE 

8192 

EXPORTS 

WndProc 


® Figure 1113: 

A linker definition file for the program of Figure 11.14 









This program obtains handles to each of the 9 system pointers. Each of 
these pointers is displayed as the mouse enters a specific quadrant of 
the window (the window is conceptually divided into 9 quadrants). 

V 

#define INCL_WIN 
#include <0S2.H> 

#include <stdio.h> 

#include <process.h> 


void ErrorQuit (char *Message); /* Print error message, end program. */ 

void Quit (int ErrorCode); /* Terminate the PM program. */ 

MRESULT EXPENTRY WndProc (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 

HAB HAncBlk; /* Anchor block handle. */ 

HWND HFrame; /* Frame window handle. */ 

HMQ HMesQue; /* Message queue handle. */ 

void main () 

{ 

HWND HClient; /* Client window handle. */ 

QMSG QueMess; /* Message queue structure. */ 

ULONG CtlData = /* Control windows to include. */ 

FCF_MINMAX /* Minimize/maximize box. */ 

FCF_SHELLPOSITION /* Make window visible on screen. */ 

FCF_SIZEBORDER /* Wide sizing border. */ 

FCF_SYSMENU /* System menu. */ 

FCF_TASKLIST /* Display program name in Task Manager. */ 

FCF_TITLEBAR; /* Title bar. */ 

HAncBlk = Winlnitialize /* Returns an anchor block handle. */ 

(0); /* Initialization options: must be 0. */ 

HMesQue = WinCreateMsgQueue /* Returns a message queue handle. */ 

(HAncBlk, /* Anchor block handle. */ 

0); /* Minimum queue size: 0 means default size.*/ 

WinRegisterClass /* Register a window class. */ 

(HAncBlk, /* Anchor block handle. */ 

"MAIN", /* Window class name. */ 

WndProc, /* Window procedure associated with class. */ 

0L, /* Class style: no styles specified. */ 

0); /* Bytes of data storage for each window. */ 

HFrame = WinCreateStdWindow /* Create a standard window collection. */ 

(HWND_DESKTOP, /* Parent window handle. */ 

WS_VISIBLE, /* Frame window style. */ 

SCtlData, /* Address of control data. */ 

"MAIN", /* Client window class name. */ 

": System Pointer Demo", /* Text for title bar. */ 

°L, /* Client window style: none specified. */ 


Figure 11.14: 

A program that displays the system mouse pointers 
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@ 


while 


0, 

/* 

0, 

/* 

&HClient); 

/* 

(WinGetMsg 

/* 

(HAncBlk, 

/* 

SQueMess, 

/* 

0, 

/* 

0, 

/* 

0)) 

/* 


Resource module handle: none. 

Resource identification: none 
Address to receive client window hand. 

Get messages until WM_QUIT. 

Anchor block handle. 

Address of message structure. 

Window filter: any window. 

First message identifier: n/a. 

Last message identifier: n/a. 


WinDispatchMsg (HAncBlk,SQueMess); /* Dispatch messages. 


*/ 

*/ 

V 

*/ 

*/ 

V 

*/ 

V 

*/ 

V 


Quit (0) ; 


/* Exit program with 0 error level. */ 


} /* end main */ 


/*** The window procedure and subroutines. 




MRESULT EXPENTRY Create 
MRESULT EXPENTRY Destroy 
MRESULT EXPENTRY MouseMove 
MRESULT EXPENTRY Size 


(HWND hwnd, USHORT msg, 
(HWND hwnd, USHORT msg, 
(HWND hwnd, USHORT msg, 
(HWND hwnd, USHORT msg, 


MPARAM mpl, MPARAM mp2); 
MPARAM mpl, MPARAM mp2); 
MPARAM mpl, MPARAM mp2); 
MPARAM mpl, MPARAM mp2)? 


HPOINTER HandleTable [4] [2]? 


/* Array for holding 8 pointer handles. 


static SHORT xQuart; 
static SHORT yHalf; 


/* 1/4 horizontal dimension of window. 
/* 1/2 vertical dimension of window. 


MRESULT EXPENTRY WndProc 
(HWND hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2) 


/* Window handle. 

/* The message. 

/* Message-specific information. 
/* Message-specific information. 


{ 

switch (msg) 

{ 

case WM_CREATE: 

return Create (hwnd,msg,mpl,mp2); 


*/ 

*/ 

*/ 


*/ 

*/ 

*/ 

*/ 


case WM_DESTROY: 

return Destroy (hwnd,msg,mpl,mp2); 


case WM_ERASEBACKGROUND: /* Have the system erase the window. */ 

return TRUE; 


case WM_MOUSEMOVE: 

return MouseMove (hwnd,msg,mpl,mp2)? 
case WM_SIZE: 

return Size (hwnd,msg,mpl,mp^)*; 

default: /* Perform the default processing on all other messages. */ 


® Figure 11.14: 

A program that displays the system mouse pointers (continued) 
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return WinDefWindowProc (hwnd,msg,mpl,mp2) ; 

} 

} /* end WndProc */ 

MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* Test for presence of mouse? quit if no mouse is installed. */ 

if (1WinQuerySysValue 
(HWND_DESKTOP, 

SV_MOUSEPRESENT)) 

ErrorQuit ("Sorry, you must have a mouse.")? 

/* Obtain handles for the 9 system pointers. */ 

HandleTable [0][0] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_ARROW, /* Normal arrow pointer. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

HandleTable [0][1] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR__TEXT, /* Text I-beam. */ 

FALSE)? /* do not make a new copy of pointer. */ 

HandleTable [0][2] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_WAIT, /* Hour-glass pointer. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

HandleTable [0][3] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_MOVE, /* Move pointer. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

HandleTable [1][0] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_SIZENWSE, /* Downward sloping, double-headed. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

HandleTable [1][1] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_SIZENESW, /* Upward sloping, double-headed. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

HandleTable [1][2] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_SIZEWE, /* Horizontal, double-headed. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

HandleTable [1][3] = WinQuerySysPointer 

(HWND_DESKTOP, /* Desktop window handle. */ 

SPTR_SIZENS, /* Vertical, double-headed. */ 

FALSE)? /* Do not make a new copy of pointer. */ 

return FALSE? 

} /* end Create */ 

MRESULT EXPENTRY Destroy (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 


@ Figure 11.14: 

A program that displays the system mouse pointers (continued) 
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recj-ister int i,j; 

/* Release handles for the 8 system pointers, 
for (i=0;i<=l;++i) 

for (j=0;j<=3;++j) 

WinDestroyPointer 

(HandleTable [i][j])7 

} /* end Destroy */ 

MRESULT EXPENTRY MouseMove (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* Assign one of the 8 pointers depending upon the window quadrant 
containing the mouse. 

WinSetPointer 

(HWND_DESKTOP, 

HandleTable [MOUSEMSG(&msg)->y / yHalf] 

[MOUSEMSG(&msg)->x / xQuart]); 

return TRUE; 

} /* end MouseMove */ 


MRESULT EXPENTRY Size (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* Save dimensions of a single quadrant. 
xQuart = SHORT1FROMMP (mp2) / 4 + 1; 
yHalf = SH0RT2FROMMP (mp2) / 2 + 1? 

return FALSE; 

} /* end Size */ 


void ErrorQuit /* Terminate program due to fatal error condition. */ 

(char *Message) /* Error message to display to user. */ 

{ 

char Buffer [60] ; 


sprintf (Buffer,"Program Error: %s",Message); 


WinMessageBox 

/* 


(HWND_DESKTOP, 

/* 


HFrame, 

/* 


Buffer, 

/* 


"Pointer Demo", 

/* 


0 , 

/* 


MB OK | 

/* 


MB_ICONHAND); 

/* 

Quit 

(1) ? 

/* 

} /* 

end ErrorQuit */ 



Display a message box. 

Handle of parent: desktop window. 
Handle of owner: frame window. 
Message text. 

Caption. 

Help window ID: not needed. 
Display an 'OK' button. 

Display a hand icon. 

Call normal termination function. 


*/ 

*/ 

V 
*/ 
*/ 

V 

V 
*/ 

*/ 


® Figure 11.14: 

A program that displays the system mouse pointers (continued) 
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void Quit (int ErrorCode) 

{ > 

WinDestroyWindow (HFrame); 
WinDestroyMsgQueue (HMesQue); 
WinTerminate (HAncBlk); 
exit (ErrorCode) ; 

} /* end Quit */ 


• Figure 11.14: 

A program that displays the system mouse pointers (continued) 

The program obtains handles to each of the system pointers by call¬ 
ing WinQuerySysPointer (Figure 11.7) during processing of the 
WM_CREATE message. These handles are stored in the two-dimen¬ 
sional array HandleTable (the first dimension corresponds to the row 
in which the pointer will be displayed, and the second dimension cor¬ 
responds to the column). These handles are later released by calling 
WinDestroyPointer (Figure 10.10) during processing of the WM_DES- 
TROY message (which is sent when the window is removed). 

The function Size, activated through the WM_SIZE message (Figure 
3.22), maintains the global variables xQuart and yHalf, which store the 
horizontal and vertical sizes of a single quadrant; each quadrant is ap¬ 
proximately one-quarter the current width of the window and one-half the 
height. These values are calculated through the following expressions: 

xQuart = SHORT1FROMMP (mp2) / 4 + 1; 
yHalf = SHORT2FROMMP (mp2) / 2 + 1; 

Remember that the low-order word of mp2 contains the horizontal size 
of the client window, and the high-order word contains the vertical size. 
(The + 1 terms in these expressions prevent addressing beyond the 
bounds of the HandleTable array in the function call to WinSetPointer, 
explained next. Note that the eight quadrants into which the window is 
divided are only approximately equal.) 

Finally, the function that processes the WM_MOUSEMOVE function 
calls WinSetPointer to set the mouse pointer according to the specific 
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screen quadrant currently containing the pointer. This function call is 
as follows: 

case WM MOUSEMOVE: 


WinSetPointer 
(HWND_DESKTOP, 

HandleTable [MOUSEMSG(&msg)->y / yHalf] 

[MOUSEMSG(&msg)-> x / xQuart]); 

Note that the MOUSEMSG macro is analogous to the CHARMSG and 
COMMANDMSG macros, and provides a convenient method for 
extracting both the vertical (MOUSEMSG(&msg)->y) and horizontal 
(MOUSEMSG(&msg)->x) coordinates of the mouse pointer. 

Note also that the window procedure does not contain a proce¬ 
dure for processing the WM_PAINT message, which normally per¬ 
forms the task of erasing the client window (that is, filling it with the 
background color) each time this window becomes invalid. Rather, 
the client window procedure forces the system to erase the window 
by simply returning TRUE whenever it receives the WM_ERASE- 
BACKGROUND message (Figure 11.15). Returning TRUE from this 
message is an easy and efficient method for erasing the client window; 


WM_ERASEBACKGROUND 

Purpose: 

This message is sent to the client window so that the client 
window procedure can either erase the window itself, or 
have the system erase the window using the default back¬ 
ground color (CLR_B ACKGROUND). 


• Figure 11.15: 

The WM_ERASEB ACKGROUND Presentation Manager message 
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Parameters: 

mparam mpi Handle to a presentation space that can be 

used to erase the window if the client 
window procedure chooses to perform this 
operation. 

MPARAM m P 2 Address of a WRECT structure (defined 

below) containing the dimensions of the 
rectangle to be erased. 

Stmcture: 

typedef struct _WRECT 

{ 

SHORT xLeft; 

SHORT dummy1; 

SHORT yBottom; 

SHORT dummy2; 

SHORT xRight; 

SHORT dummy3; 

SHORT yTop; 

SHORT dummy4; 

1 

WRECT; 

Return Value: 

The client window procedure should return TRUE to force 
the system to erase the window; it should return FALSE if it 
has performed the erasing operation itself. 

Notes: 

Returning TRUE from this function is an efficient method for 
erasing the client window. The message is sent by the frame 
window procedure whenever the frame window is in¬ 
validated (it is sent by the routine that processes the 
WM_PAINT message); the message is therefore not sent 
when the client window alone is invalidated. 


• Figure 11.15: 

The WM_ERASEBACKGROUND Presentation Manager message (continued) 




Adding a Mouse Interface 563 • 


however, since the message is sent only when the frame window is in¬ 
validated, the technique would fail if the client window alone were in¬ 
validated (for example, the text editor presented in the first part of this 
book frequently calls the function WinlnvalidateRect to invalidate only 
the client window; this program can therefore not rely upon the 
WMJERASEBACKGROUND message for erasing the client window). 


. READING THE MOUSE BUTTONS 

The third important mouse parameter discussed in this chapter is 
the state of the mouse buttons; that is, whether a given mouse button 
is pressed or released. A mouse used with the Presentation Manager can 
have either one, two, or three buttons. You can determine the number of 
buttons available by calling the WinQuerySys Value function (Figure 
11.1), passing the identifier SV_CMOUSEBUTTONS, as follows: 

LONG NumberButtons; 


NumberButtons = WinQuerySysValue 
(HWND_DESKTOP, 

SV_CMOUSEBUTTONS); 

Normally, when calling Presentation Manager functions or process¬ 
ing messages, the buttons are numbered from left to right. Accordingly, 
the button on the left is known as button number 1, the next button 
to the right (if present) is known as button number 2, and the next but¬ 
ton (if present) is known as button number 3. However, the user can 
swap this ordering (using the Control Panel) so that the buttons are 
numbered from right to left. The ordering of the buttons is not impor¬ 
tant to the program, unless it issues instructions such as Now press the 
left mouse button/' The program can determine whether the button or¬ 
dering has been swapped by calling WinQuerySysValue, passing this 
function the value SV_SWAPBUTTON, as follows: 
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BOOL ButtonsSwapped; 


ButtonsSwapped = (BOOL)WinQuerySysValue 
(HWND_DESKTOP, 

SV_SWAPBUTTON); 

(Note that your program can also set the swapped state of the mouse 
buttons by calling the WinSetSysValue function.) 

If your program uses more than one mouse button, you should pro¬ 
vide alternative commands that can be issued using a single button. For 
example, in the program listed in Figure 11.21 (described later in this 
section), the command issued by pressing mouse button 2 can also be 
issued by pressing button 1 in conjunction with the Alt key. 

Just as you can obtain the position of the mouse pointer either by call¬ 
ing a function or by processing a message, you can likewise determine 
the status of the mouse buttons either by calling the WinGetKeyState 
function or by processing the appropriate mouse messages. 

The WinGetKeyState function (Figure 11.16) can be called to obtain 
the status of a virtual key (see the explanation of virtual keys in Chapter 
6) or a mouse button. You can pass this function a value identifying a 
specific mouse button, and it will return a value less than 0 if the button 
is pressed, or a value of 0 or greater if the button is released. A given 
mouse button is specified by passing one of the following values: 

VK_BUTTONl 

VK_BUTTON2 

VK_BUTTON3 

The following example determines whether mouse button 2 is pressed: 
BOOL Button2Pressed; 


Button2Pressed = WinGetKeyState 
(HWND__DE SKTOP, 

VK_BUTTON2) < 0; 
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Note that the button status returned by WinGetKeyState is the status 
of the button at the time the last message obtained from the queue was 
posted. This function is thus analogous to WinQueryMsgPos (which 
obtains the pointer position at the time the last queue message was 


WinGetKeyState 

Purpose: 

Determines whether a virtual key or mouse button is cur- 
rently pressed or released; also returns the toggle status of a 
key. 


Prototype: 


SHORT APIENTRY WinGetKeyState 


(HWND hwndDesktop, 
SHORT vkey); 


The value HWND_DESKTOP to 
identify the desktop window. 
Identifier for the virtual key (see Table 
6.1), or one of the following codes 
identifying a mouse button: 


VKJBUTTON1 

VK_BUTTON2 

VKJBUTTON3 


Return Value: 

If the specified key or mouse button is pressed, the high 
order bit of the word value returned by this function is set 
(that is, the return value will be negative); otherwise, this bit 
will be cleared. If the key is toggled, the low-order bit of the 
return value is set; a key is toggled if it has been pressed an 
odd number of times since the system was started. 


Notes: 

The value returned by this function is the status of the key at 
the time the last message obtained from the queue was 
posted. 


• Figure 11.16: 

The WinGetKeyState Presentation Manager function 
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posted). There is no function analogous to WinQueryPointerPos for ob¬ 
taining the current button state. 

The system also informs the client window of the status of the mouse 
buttons by sending it an appropriate message whenever a button is first 
pressed or released. These messages are summarized in Table 11.2. 

Whenever the user presses mouse button 1, the system sends the 
WM.BUTTONIDOWN message; when this button is subsequently 
released, the system sends WM_BUTTONlUP. The system sends 
analogous messages for buttons 2 and 3. The action of pressing and 
releasing a mouse button is termed a click. If the user clicks button 1 
twice in rapid succession, with the mouse pointer in the same screen 
area, the system sends the following sequence of messages: 

WM_BUTTON 1 DOWN 
WM_BUTTON 1 UP 
WM_BUTTON 1DBLCLK 
WM_BUTTON 1 UP 

Note that the message WM_BUTTONl DBLCLK has replaced the 
second WM_BUTTON 1 DOWN message to indicate that the two clicks 


* Table 11.2: TheMouseButtonStatusMessages 


Message ID 

“ O - 

Button Event 

WM_BUTTON 1 DOWN 

Button 1 has been pressed 

WM_BUTTON 1 UP 

Button 1 has been released 

WM_BUTTON2DOWN 

Button 2 has been pressed 

WM_BUTTON2UP 

Button 2 has been released 

WM_BUTTON3DOWN 

Button 3 has been pressed 

WM_BUTTON 3UP 

Button 3 has been released 

WM_BUTTONl DBLCLK 

Button 1 has been double-clicked 

WM_BUTTON2DBLCLK 

Button 2 has been double-clicked 

WM_BUTTON3DBLCLK 

Button 3 has been double-clicked 


_“ _ 1 
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qualify as a double click. A double click consists of two clicks that oc¬ 
cur within a certain short time span while the mouse pointer is con¬ 
tained within a certain small screen area. The user can set the time span 
through the Control Panel. Also, you can obtain or set the current 
values for both the double-click time and the sensitive screen area by 
calling WinQuerySysValue or WinSetSysValue (passing the constant 
SV DBLCLKTIME for the time, SV_CXDBLCLK for the width of the 
area, or SV_CYDBLCLK for the height of the area). The system sends 
the analogous messages listed in Table 11.2 for buttons 2 and 3. 

Providing a special message for double-clicking expands the possi e 
number of commands the user can issue with the mouse. The next sec¬ 
tion describes how these commands are typically used by an application. 

Figures 11.17 through 11.21 provide an example program that 
demonstrates how to design and install a custom mouse pointer, and 
how to execute commands in response to mouse button activity. Figure 
11 17 lists a MAKE file for preparing the program; Figure 11.18 is the 
linker definition file; Figure 11.19 is a resource script that defines 
the mouse pointer; Figure 11.20 is a header file that is included in 
Figures 11.19 and 11.21; and Figure 11.21 is the C source code. 

The custom mouse pointer used in this program was created in the 
Icon Editor, as described in Chapter 10; it was then saved in the file 


# This MAKE file prepares the program of Figure 11. 

FIG11 21. OBJ : FIG11_21.C FIG11_20.H 
cl /W2 /c /Zp /G2ws FIG11_21.C 


FIG11_.L9.RES : FIG11_19.RC FIG11_20.H 

re ,/r FIG11_19.RC 


FIG11_21.EXE : FIG11_21.0BJ FIG11_ 
link /NOD FIG11_21.0BJ,, NUL, 
rc FIG11_19.RES FIG11_21.EXE 


18.DEF FIG11_19.RES 
OS2.LIB SLIBCE.LIB, 


FIG11_18.DEF 


9 Figure 11.17: 

A MAKE file for preparing the program of Figure 1121 
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FIG11_19.PTR. The pointer has the shape of a paintbrush, and it is used 
for drawing lines within the client window. The pointer is defined in 

the resource file of Figure 11.19 as follows: 

POINTER ID_POINTER "FIG11 19.PTR" 


; Figure 11.18 

' Linker definition file for the program listed in Figure 11.21 

NAME FIG11 21 

PROTMODE 

HEAPSIZE 1024 

STACKSIZE 8192 

EXPORTS WndProc 


• Figure 11.18: 

A linker definition file for the program of Figure 11.21 


/* 

Figure 11.19 

Resource script for the program of Figure 11.21 

*/ 

#include "FIG11 20.H" 

POINTER ID_POINTER "FIGll 19.PTR" 

® Figure 11.19 : 

A resource script for the program of Figure 11.21 


/* 

Figure 11.20 

Header file included in the listings of Figures 11.19 and 11 21 

*/ 

#define ID_POINTER 1 


® Figure 11.20: 

A header file included in the listings of Figures 11.19 and 11.21 
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*/ 


Figure 11.21 

This program displays a custom mouse pointer, and responds to the mouse 
buttons by drawing lines within the wind 


#define INCL_WIN 
#include <0S2.H> 

#include "FIG11_20.H" 
#include <stdio.h> 

#include <process.h> 


void ErrorQuit (char *Message); 
void Quit (int ErrorCode); 
MRESULT EXPENTRY WndProc (HWND 


/* Print error message, end program. 

/* Terminate the PM program, 
hwnd, USHORT msg, MPARAM mpl, MPARAM mp2); 


HAB HAncBlk; 
HWND HFrame; 
HMQ HMesQue; 


/* Anchor block handle. 
/* Frame window handle. 
/* Message queue handle 


*/ 

V 


*/ 

*/ 

*/ 


void main () 

( 

HWND HClient; 

QMSG QueMess; 

ULONG CtlData = 

FCF_MINMAX | 

FCF_SHELLPOSITION 
FCF_SIZEBORDER 
FCF_SYSMENU 
FCF_TASKLIST 
FCFJTITLEBAR? 

HAncBlk = Winlnitialize 

( 0 ) ? 


/* client window handle. / 

/* Message queue structure. ^ / 

/* Control windows to includes / 

/* Minimize/maximize box. / 

/* Make window visible on screen. / 

/* Wide sizing border. J 

/* System menu. J 

/* Display program name in Task Manager. / 

/* Title bar. / 

/* initialize the Presentation Manager. V 

/* initialization options: must be 0. / 


HMesQue = WinCreateMsgQueue /* Create a i me ® s ^e ?u eue 
(HAncBlk, /* Anchor block handle. 


*/ 

*/ 


0 ) 


/* 


An CIIO I. */ 

Minimum queue sizes 0 means default si . / 


WinRegisterClass /* 

(HAncBlk, /* 

"MAIN”, /* 

WndProc, /* 

CS SIZEREDRAW, /* 

0 ) ; /* 


HFrame = WinCreateStdWindow 
(HWND_DESKTOP, 
WS_VISIBLE, 

&CtlData, 

"MAIN", 

": Mouse Button Demo", 
0L, 

0 , 


Register a window class. 

Anchor block handle. 

Window class name. _ 

Window procedure associated with class. 
Invalidate entire window on size change. 
Bytes of data storage for each window. 

/* Create a standard window collection. 
/* Parent window handle. 

/* Frame window style. 

/* Address of control data. 

/* Client window class name. 

/* Text for title bar. „ 

/* client window styles none specified. 
/* Resource module handles none. 


*/ 

*/ 

*/ 

V 

*/ 

V 


V 

*/ 

V 

V 
*/ 
*/ 
*/ 
*/ 


* ATIxampfeprogram that displays a custom mouse pointer and responds to the mouse buttons 
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0 , 

&HClient); 

while (WinGetMsg 
(HAncBlk, 
SQueMess, 

0 , 

Or 

0 ) ) 


/* Resource identification: none */ 

/* Address to receive client window hand. */ 


/* Get messages until WM_QUIT. 

/* Anchor block handle. 

/* Address of message structure. 
/* Window filter: any window. 

/* First message identifier: n/a. 
/* Last message identifier: n/a. 


WinDispatchMsg (HAncBlk, SQueMess); /* Dispatch messages. 

Quit (0); /* Exit program with a 0 error level. 

} /* end main */ 


*/ 

*/ 

V 

V 

V 

*/ 

V 

*/ 


/*** The window procedure and subroutines. ***********************************/ 

MReIul? EXPENTOY Button2Dn Sn r ? H ° RT mSg ' MPARAM MPARAM mp2); 

MRESULT EXPENTRY Create USH0RT ms 9' MPARAM mpl, MPARAM mp2 ; 

MRESULT EXPENTRY Destroy HWND 2 °™” ” Sg ’ MPARAM “P 1 ' Mp A*AM mp2 ; 

!=S KX Sis s us ;S: us s; 


static HPOINTER HMousePtr; 
POINTL SavedPoint = {0,0}; 

MRESULT EXPENTRY WndProc 
(HWND hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2) 

{ 


/* Handle of the mouse pointer. 

/* Saved value of last line endpoint. 


/* Window handle. 

/* The message. 

/* Message-specific information. 
/* Message-specific information. 


switch (msg) 

{ 

/* Button 1 has been pressed, 
case WM_BUTT0N1D0WN: 

return ButtonlDn (hwnd,msg,mpl,mp 2 ); 

/* Button 2 has been pressed, 
case WM_BUTT0N2D0WN: 

return Button2Dn (hwnd,msg,mpl,mp2); 

case WM__CREATE: 

return Create (hwnd,msg,mpl,mp2); 
case WM_DESTROY: 

return Destroy (hwnd,msg,mpl,mp2); 

/* Force the system to erase the client window, 
case WM_ERASEBACKGROUND: 
return TRUE; 

/* The mouse has moved within the client window. 


V 

V 


V 
*/ 

V 

V 


• Figure 11.21: 

An example program that displays a custom mouse pointer and responds to the mouse buttons (continued) 
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case WM_MOUSEMOVE: 

return MouseMove (hwnd,msg,mpl,mp2) ; 
default: 

return WinDefWindowProc (hwnd,msg,mpl,mp2); 

) 

} /* end WndProc */ 


MRESULT EXPENTRY ButtonlDn (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

( 

HPS HPresSpace; 


/* 

if 


If Alt key is pressed, send a WM_BUTT0N2D0WN message. 
(WinGetKeyState 
(HWND_DESKTOP, 

VK_ALT) < 0) 

{ 

WinSendMsg 
(hwnd, 

WM_BUTTON 2 DOWN, 

mpl, 

mp2) ; 

return TRUE; 

} 


from current point to mouse pointer position. 
/* Obtain a presentation space. 

/* Set PM current graphics point to 
/* last endpoint. 


/* otherwise, draw a line 
HPresSpace = WinGetPS (hwnd); 
GpiMove 

(HPresSpace, 

SSavedPoint); 

SavedPoint.x = MOUSEMSG(&msg)->x; 
SavedPoint.y = MOUSEMSG(&msg)->y? 
GpiLine 

(HPresSpace, 

&SavedPoint); 

WinReleasePS (HPresSpace)? 


/* Adjust 'SavedPoint' to current 
/* pointer position. 

/* Draw line from graphics point to 
/* current mouse pointer position. 


/* Release the presentation space. 


V 


V 

V 

V 

V 

V 

*/ 

V 

V 


*/ 


return TRUE; 


/* Notify system that message has been processed. */ 


} /* end ButtonlDn */ 


MRESUI.T EXPENTRY Button2Dn (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* Reset 'SavedPoint' to current mouse position. 

SavedPoint.x = MOUSEMSG(&msg)->x; 

SavedPoint.y = MOUSEMSG(&msg)->y; 


return TRUE; 

} /* end Button2Dn */ 


ATexampleprogmm that displays a custom mouse pointer and responds to the mouse buttons (continued) 




Programmer's Guide to the OS/2 Presentation Manager 


MRESULT EXPENTRY Create (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* Quit program if mouse not installed, 
if (!WinQuerySysValue 
(HWND_DESKTOP, 

SV_MOUSEPRESENT)) 

ErrorQuit ("Program requires mouse"); 

/* Load custom pointer resource. 

HMousePtr = WinLoadPointer 
(HWND_DESKTOP, 

NULL, 

ID_POINTER); 

if (HMousePtr == NULL) 

ErrorQuit ("Cannot load pointer resource"); 

return FALSE; 

} /* end Create */ 


MRESULT EXPENTRY Destroy 
{ 

WinDestroyPointer 
(HMousePtr); 

) /* end Destroy */ 


MRESULT EXPENTRY MouseMove (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* the mouse pointer to the custom pointer while the mouse is in the 

client window. 

WinsetPointer 

(HWND_DESKTOP, 

HMousePtr); 

return TRUE; 

} /* end MouseMove */ 


(HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2) 

/* Release pointer handle. */ 


void ErrorQuit 

(char *Message) 

{ 

char Buffer [60]; 


/* Terminate program due to fatal error condition. */ 
/* Error message to display to user. */ 


sprintf (Buffer,"Program Error: %s",Message); 

WinMessageBox /* Display a message box. 

(HWND_DESKTOP, /* Handle of parent: desktop window. 

HFrame, /* Handle of owner: frame window. 


V 

V 

V 


• Figure 11.21 : 

An example program that displays a custom mouse pointer and responds to the mouse buttons (continued) 
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Buffer, 

"Pointer Demo", 

0 , 

MB_OK | 

MB_ICONHAND); 

Quit (l) ; 

} /* end ErrorQuit */ 


/* Message text. 

/* Caption. 

/* Help window ID: not needed. 

/* Display an 'OK' button. 

/* Display a hand icon. 

/* call normal termination function. 


V 

*/ 

*/ 

*/ 

*/ 

*/ 


void Quit (int ErrorCode) 

WinDestroyWindow (HFrame); 

WinDestroyMsgQueue (HMesQue); 
WinTerminate (HAncBlk); 
exit (ErrorCode); 

} /* end Quit */ 


Texample program that displays a custom mouse painter and responds to the mouse buttons (continued) 

The constant ID_POINTER, defined in the header file of Figure 11.20, is 
used to identify the pointer resource when it is loaded by the C program 
(Figure 11.21). The C program loads the pointer by calling WmLoad- 
Pointer (Figure 10.8) during processing of the WM_CREATE message, 
as follows: 


HMousePtr = WinLoadPointer 
(HWND_DESKTOP, 

NULL, 

ID_POINTER); 

HMousePtr is defined as an external variable through the following 
expression: 

static HPOINTER HMousePtr; 

The pointer is released during processing of the WMJDESTROY 
message using the following call to WinDestroyPointer. 

WinDestroyPointer 
(HMousePtr); 
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The program causes the system to display the custom mouse pointer 
while the pointer is located within the client window by issuing the fol¬ 
lowing call to WinSetPointer each time the client window procedure 
receives the WM_MOUSEMOVE message: 

WinSetPointer 

(HWND_DESKTOP, 

HMousePtr) ; 

Note that the WMMOUSEMOVE routine (the function MouseMove) 
ignores the current pointer position; the WM_MOUSEMOVE message 
is used simply as an indication that the pointer is currently located 
somewhere within the client window. 

The example program processes two mouse button messages: the 
WM_BUTTONl DOWN message, sent when button 1 is pressed, and 
the WM_BUTTON2DOWN message, sent when button 2 is pressed. 
The WM_BUTTONlDOWN message is processed in the function But- 
tonlDn, and the WM_BUTTON2DOWN message is processed in But- 
ton2Dn. In response to button 1, ButtonlDn draws a line from the 
point saved in the variable SavedPoint to the current mouse position 
(SavedPoint is a global POINTL structure that is initialized to the value 
{0,0}). ButtonlDn also updates SavedPoint to contain the current 
mouse position. Thus, the user can draw a sequence of connected line 
segments as shown in Figure 11.24 (described later). 

The function ButtonlDn draws a line segment by performing the fol¬ 
lowing steps: 

1. It calls WinGetPS (Figure 3.19) to obtain a handle to a presenta¬ 
tion space. 

2. It calls GpiMove (Figure 11.22) to set the current graphics position 
maintained by the Presentation Manager to the value contained 
in SavedPoint. This point will become the start of the line 
segment. 

3. It calls GpiLine (Figure 11.23), which draws a line from the cur¬ 
rent graphics point to a specified point. The point specified by 
ButtonlDn is the current mouse position. GpiLine thus draws a 
line segment from the point that was stored in SavedPoint to the 
current position of the mouse pointer. Note that the current 
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pointer position accompanies all mouse messages, and it is easily 
extracted using the MOUSEMSG macro. 

4. It calls WinReleasePS (Figure 3.22) to release the presentation 
space. 


GpiMove 

Purpose: 

Sets the current graphics position. 

GpiMove 

Handle to a presentation space. 

Address of a POINTL structure (defined in 
Figure 3.28) containing the new graphics 
position. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

The current graphics position is initialized to the point (0,0) 
when the presentation space is first obtained. GpiMove ex¬ 
plicitly sets the current graphics position; drawing functions 
such as GpiLine also set this position (to the specified en¬ 
ding point of the primitive that is drawn). 

Related Functions: 

GpiLine (Figure 11.23) 


• Figure 11.22: 

The GpiMove Presentation Manager function 


Prototype: 

bool apientry 

(HPS hps, 
PPOINTL pptl); 
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GpiLine 

Purpose: 

Draws a straight line from the current graphics position to 
the specified endpoint, and resets the current graphics posi¬ 
tion to this endpoint. 

Prototype: 

LONG APIENTRY GpiLine 

(hps hps , Handle to the presentation space in which 

the line is to be drawn. 

ppointl pptl) ; Address of a POINTL structure (defined in 
Figure 3.28) containing the endpoint. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

The beginning point of the line is the current graphics posi¬ 
tion; since GpiLine resets the current graphics position to 
the specified endpoint, you can draw a sequence of con¬ 
nected line segments in a given presentation space by 
repeatedly calling GpiLine, without explicitly setting the 
current graphics position between calls. You can call Gpi- 
Move, however, if you need to explicitly set the graphics 
position. 

Related Functions: 

GpiMove (Figure 11.22) 

® Figure 11.23: 

The GpiLine Presentation Manager function 
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Note that rather than accepting both a starting point and an ending 
point, the function GpiLine receives only the ending point of the line. 
The starting point of the line is the current graphics position that is 
maintained by the Presentation Manager for a given presentation space. 
When you first obtain a presentation space, the current graphics posi¬ 
tion is initialized to the point (0,0). You can explicitly set it to an ar¬ 
bitrary point by calling GpiMove; also, certain drawing functions, such 
as GpiLine, reset the current position to the endpoint of the object 
drawn. Thus, if the desired beginning point of the line is not the current 
graphics position, you must call both GpiMove and GpiLine to fully 
specify the line. 

If, however, you are drawing a series of connected line segments 
within a given presentation space, you need to call GpiMove only to set 
the initial starting point. Since GpiLine automatically resets the current 
point to the endpoint of the line drawn, you can draw each subsequent 
connected line segment by simply calling GpiLine. (Even though the 
line segments drawn by the program of Figure 11.21 are connected, But- 
tonlDn must always call GpiMove, since it obtains a handle to a new 
presentation space each time it is called.) 

In response to mouse button 2, the function Button2Dn resets Saved- 
Point to contain the current mouse position, using the following expressions: 

SavedPoint.x = MOUSEMSG(&msg)-> x; 

SavedPoint.y = MOUSEMSG(&msg)-> y; 

Pressing button 2 thus allows the user to reset the starting point in order 
to draw a new series of connected line segments. 

The function Button2 receives control either when the user presses 
mouse button 2 or when the user presses button 1 in combination with the 
Alt key (which is a provision for users with a single mouse button). When¬ 
ever the user presses button 1, the function ButtonlDn receives initial con¬ 
trol; if, however, the Alt key is also pressed, ButtonlDn immediately 
passes control to Button2Dn, through the following instructions: 

if (WinGetKeyState 
(HWND__DESKTOP, 

VK_ALT) < 0) 

{ 

WinSendMsg 
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(hwnd, 

WM_BUTTON2DOWN , 

mpl, 

mp2) ; 

return TRUE; 

} 

Note that the program of Figure 11.21 (like the program of Figure 
11.14) erases the client window by returning TRUE from the 
WM_ERASEBACKGROUND message. Accordingly, the client window 
is cleared whenever the frame window is resized. Figure 11.24 
illustrates the window and mouse pointer created by the program. 


• CREATING A MOUSE INTERFACE 

The previous sections have described the basic mouse operations: 
determining the pointer position, setting the pointer shape, and reading 
the status of the mouse buttons. This section briefly describes how to 
use these basic operations to create a standard mouse interface. The 
guidelines described in this section are derived from the Presentation 



® Figure 11.24: 

The window created by the program of Figure 11.21 
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Manager technical documentation and the Windows Application Style 
Guide (see the Bibliography). As mentioned in Chapter 5, your applica¬ 
tion will be easier for the user to learn and use if it conforms to the 
standard interface. 

In general, a Presentation Manager application should provide 
mouse commands for all operations that can be easily and efficiently ac¬ 
complished with the mouse. Note, however, that installing a mouse is 
optional; the user should be able to run Presentation Manager applica¬ 
tions without a mouse (except for highly specialized programs that 
would be impractical without a mouse). Therefore, you should provide 
alternative keyboard commands for all mouse operations. 

The following table defines the basic terms used to describe the ac¬ 
tions that can be performed with a mouse: 


Action 

Description 

Click 

Quickly pressing and releasing the mouse 
button 

Double-click 

Clicking the mouse twice in rapid succession, 
while the mouse pointer remains in the same 


screen area 

Drag 

Pressing the mouse button, and holding it 
down while moving the mouse 

Point 

Placing the pointer hot spot (for example, the 
tip of the standard arrow pointer) on a specific 
item or within a given area 


Mouse Commands 

This section lists the standard uses for mouse button 1. The use of 
mouse button 2 is application-specific; note, however, that a program 
should not depend upon the existence of more than a single button. Ac¬ 
cordingly, a command issued through button 2 should be optional (a 
command shortcut, for example), or you should implement an alterna¬ 
tive keyboard command (possibly executed in combination with mouse 
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button 1). Mouse button 3,if present, is reserved for optional system 
commands. 

The following commands are recommended for marking selections 
within text-based applications (see Chapter 9 for a discussion on text 
selections and their relationship with the Presentation Manager clip¬ 
board). Note that the recommended pointer for an area displaying text 
is the I-beam (identified by the value SPTR_TEXT). 


Mouse Command 

Effect 

Click 

Moves the text insertion point to the 
position under the pointer 

Double-click 

Selects the word under the pointer 

Shift-click 

Extends the selection from the current 
text insertion point or text selection 
through the position under the pointer 

Drag 

Selects text from the position where the 
button was pressed to the position 
where the button was released 

Shift-drag 

Extends the selection from the current 
insertion point or text selection 
through the area selected by dragging 
the mouse 


Note that using the Shift key in conjunction with the mouse button in¬ 
creases the number of commands that could be issued through the basic 
mouse actions alone. 

The following commands are recommended for selecting items from 
lists (for example, selecting files from a list of file names). Note that the 
standard arrow pointer (SPTR_ARROW) is recommended for selecting 
list items. 

Mouse Command Effect 


Click 


Selects the item under the pointer (for 
example, highlights a file name in a 
list) 
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Double-click 


Shift-click 


Drag 


Ctrl-click 


Ctrl-drag 


Selects the item under the pointer and 
performs the default action on that 
item (for example, highlights a file 
name and reads the file) 

Extends the selection from the pre¬ 
viously selected item(s) to the item 
under the pointer 

Selects all items extending from the 
position where the button was pressed 
to the position where the button was 
released 

Selects a single discontinuous item 
(that is, the previous selection remains 
intact, and the newly selected item is 
added to the selection without adding 
intermediate items) 

Selects a group of discontinuous items 
(that is, the previous selection remains 
intact, and the newly selected items 
are added to the selection without ad¬ 
ding intermediate items) 




. 1 


I 

«in 
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C hapter 1 introduced the topic of multitasking and de¬ 
scribed the three levels of multitasking supported by 
OS/2: multiple screen groups, multiple programs, and 
multiple threads of execution within a single program. 
This chapter focuses on the finest of these three levels: multitasking of 
threads. Specifically, it describes how to use multiple threads of execu¬ 
tion within a Presentation Manager application. 

All of the Presentation Manager programs described so far in this 
book have consisted of a single thread. In these programs, when the 
function main calls WinDispatchMsg to dispatch a message, control 
does not return from WinDispatchMsg until the message has been 
fully processed and the window procedure has issued a return state¬ 
ment. Thus, messages are processed one at a time, and only one func¬ 
tion within your program is active at a given time. 

In general, using multiple threads of execution within a single ap¬ 
plication is a useful device for increasing program efficiency and 
throughput, and for simplifying complex program logic. Specifically, 
under the Presentation Manager, starting multiple threads is an impor¬ 
tant technique for performing lengthy tasks in response to keyboard or 
mouse commands. 

Since a program consisting of a single thread can process only one 
message at a time, a message that initiates a lengthy operation (such as 
recalculating a spreadsheet or printing a file) blocks the program from 
processing further messages until the current operation is complete. 
Thus, the program cannot respond to keyboard or mouse input while 
the operation is in progress. Furthermore, the system does not allow the 
user to switch to another application (using either the keyboard or 
mouse) while the active application is processing a message (specifical¬ 
ly, the system delays switching active applications until the window 
procedure returns control and the main message-processing loop calls 
WimGetMsg to obtain another message). Accordingly, the Presentation 
Manager documentation recommends that the window procedure 
return control within approximately 0.1 second. 

If the program consists of a single thread, the window procedure ob¬ 
viously cannot perform a lengthy operation and return control within 
0.1 second. The best solution to this problem is for the window proce¬ 
dure to start a second thread of execution to perform the lengthy opera¬ 
tion, and then return control immediately. While the second thread is 
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running, the first thread can continue to process messages and the sys¬ 
tem can allow the user to switch to another application. 

This chapter describes how to start a new thread to perform a lengthy 
operation from the window procedure. It then discusses methods for 
synchronizing the activities of the two program threads using 
semaphores and shared global variables. The chapter illustrates these 
general techniques by describing the specific steps for implementing a 
print routine within the Presentation Manager text editor presented in 
the first part of the book. Printing a file is a good example of a lengthy 
task performed in response to a keyboard or mouse message; also, run¬ 
ning a printing routine as a secondary thread illustrates many of the 
ways the activities of multiple threads must be synchronized. 

This chapter presents only one of the ways that you can exploit multi¬ 
tasking under the Presentation Manager. In addition to starting secondary 
threads of execution, a Presentation Manager application can also run 
other programs as child processes (for example, a text editor could run a 
compiler as a child process, which would allow the user to continue edit¬ 
ing while the compiler runs in the background). For further general infor¬ 
mation on multitasking and interprocess communication under OS/2, see 
the Programmer's Guide to OS/2 (cited in the Bibliography). 


• USING A SECOND THREAD 

If the window procedure needs to perform a lengthy operation, 
rather than simply calling the function that performs this operation as a 
subroutine, it can call the OS/2 function DosCreateThread (Figure 12.1) 
to execute the function as a second thread. The window procedure can 
then immediately return control to the main message-processing loop; 
while the second thread performs its task, the main thread resumes nor¬ 
mal message processing. Figure 12.2 illustrates the difference between 
executing a lengthy routine as a subroutine (part A) and running it as a 
separate thread (part B); as you can see in this illustration, the important 
benefit of starting a new thread is that it significantly shortens the mes¬ 
sage-processing loop. 
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DosCreateThread 

Purpose: 

Starts a new thread of execution within the current process. 

Prototype: 

USHORT APIENTRY DosCreateThread 

(void far *pfnFunction (void), Address of thread entry 

point. 

ptid ptidThread Pointer to variable to 

receive the thread 
identifier. 

pbyte pbThrdStack) ; Pointer to the top of the 

thread's stack. 

Return Value: 

Zero if the function was successful; if an error occurred, the 

function returns one of the following nonzero values: 

ERROR JNI 0_PR0C_SL0TS 
ERROR_NOT_ENOUGH_MEMORY 

® Figure 12.1: 

The DosCreateThread OS/2 function 


Starting the Thread 

To illustrate the techniques for using an additional thread of ex¬ 
ecution, consider the routine that processes the Print menu command in 
the text editor presented as the example application in the first part of 
the book. When the user selects the Print command from the File sub¬ 
menu, the client window receives a WM_COMMAND message with a 
command code of ID_PRINT. In the final version of the program listed 
in Figure 8.38, the routine that processes this message simply displays a 
message box informing the user that the command has not been imple¬ 
mented, and immediately returns. 





• Figure 12.2: 

Using a single thread vs. using two threads to process messages 
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The purpose of the Print command is to send the current contents of 
the file buffer to the printer. Since this process typically requires much 
more than 0.1 second, the routine that performs the actual printing 
should be executed as a separate thread. The code that starts this thread 
is listed in Figure 12.3; to implement the Print command, you should 
place this code within the function Command (of Figure 8.38), under 
the WM_PRINT case. 



© Figure 12.3: 

The routine for processing the Print menu command 
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The significant portion of this code for the present discussion is the 
following call to DosCreateThread (most of the other instructions 
manage the semaphore, and will be described later in the chapter): 

USHORT Result; 


Result = DosCreateThread 
(PrintThread, 

&IDThread, 

PrintStack 

+ sizeof (PrintStack)); 

The first parameter supplies the address of the function that the new 
thread is to begin executing. This function is declared as follows: 

VOID FAR PrintThread (VOID); 

You should use this format when declaring any function that is to be ex¬ 
ecuted as a new thread. Note that there are no parameters; the system 
does not pass parameters to the function that receives initial control 
when a new thread is started. The function PrintThread will be 
described later in the chapter. 

The second parameter to DosCreateThread supplies the address of 
the variable that is to receive the identifier of the new thread. All threads 
running under OS/2 are given unique identifiers (which must be sup¬ 
plied to functions such as DosSuspendThread). The example routine 
ignores the thread identifier. 

The final parameter contains the address of the top of the thread's 
stack. (The top of the stack is the byte immediately following the 
memory block that is reserved for the stack; note that the stack grows 
down in memory, and the stack pointer is decremented by 2 before the 
first word pushed on the stack is written to memory.) Each thread owns 
its own stack; when your program starts a new thread, it is responsible 
for reserving the memory for the new thread's stack. The required stack 
size depends upon the specific function. A recommended minimum 
size is 512 bytes; however, if the function calls any OS/2 services (or any 
other dynamic-link functions), the recommended minimum is 2048 
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bytes plus the requirements of the function itself. A generous stack size 
for the function PrintThread (which, as you will see, calls OS/2 func¬ 
tions) is 4096 bytes; this stack is declared as follows: 

BYTE PrintStack [4096]; 

Note that PrintStack is declared outside the scope of any function 
(that is, it is an external array), so that it will be permanently reserved 
within the program's data segment. You must not define the stack as a 
local variable within a function that may terminate while the thread is 
still running, since the storage for local data is relinquished upon the 
function's exit (unless it is declared as static data). Specifically, the stack 
must not be defined as local data within the function Command (which 
calls DosCreateThread), since this function typically terminates while 
the secondary thread is still running. 

In general, it is possible to execute the same function by more than 
one thread at a given time (the second thread is said to create a new in¬ 
stance of the function it executes). For example, if a program issues a 
second identical call to DosCreateThread while the thread executing 
the specified function is still active, the system will simply start another 
new thread executing the same body of code. In this case, you must al¬ 
locate a new stack for each new thread; you can allocate multiple stacks 
dynamically by calling the OS/2 function DosAllocSeg (Figure 9.1). 
Note that the example program discussed in this chapter needs to 
define only a single stack, because, as you will see later in the chapter, a 
semaphore prevents the program from calling DosCreateThread when 
the print routine is already active. 

Although each thread owns its own stack, it shares all other objects 
belonging to the program, such as memory segments and open file 
handles. Accordingly, all threads can directly access externally declared 
program data (that is, data declared outside the scope of a function). 
Also, separate threads can share all Presentation Manager objects other 
than message queues, such as windows, dialog boxes, presentation 
spaces, and resources. 

The DosCreateThread function returns immediately after beginning 
the new thread. If an error occurred, this function returns a nonzero 
error code; in this case, the example code in Figure 12.3 displays a mes¬ 
sage box informing the user of the error, and returns. 
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Writing a Function for a New Thread 

This section discusses the guidelines for writing a function that is 
to be executed as a new program thread. An example of such a function 
is PrintThread, which prints the contents of the file buffer; this function 
is listed in Figure 12.4. If you are implementing a print command for the 
text editor of Figure 8.38, you should place PrintThread within the buff¬ 
er-management module, since it directly accesses the data structures 
belonging to this module. 

The function PrintThread has the following basic structure: 

VOID FAR PrintThread (VOID) 

{ 


DosExit (EXIT_THREAD,0); 

} 

Note that although you cannot pass parameters to a function executed 
as a new thread, this function can call additional functions, passing any 
required parameters. Also, as you will see in the next section, there are 
many alternative ways for the main thread to pass information to the 
new thread. The OS/2 function DosExit (Figure 12.5) terminates 
the thread; the value EXITTHREAD, passed as the first parameter, 
causes DosExit to terminate only the current thread rather than the en¬ 
tire application. The second parameter is an exit code, which the main 
thread can retrieve, if desired, by calling the OS/2 function DosCWait. 

A function executing a new thread can freely call the Dos OS/2 ser¬ 
vices, since these functions have been designed to execute properly 
within a multitasking environment. PrintThread uses the standard 
OS/2 functions DosOpen, DosWrite, and DosClose to open the printer 
device, to write each file line to the printer, and to close the printer. (The 
other tasks performed by this function are explained in the next section.) 

A function executed as a separate thread, however, is not automat¬ 
ically free to call any Presentation Manager function. Remember that 
the message queue created by the main thread (by calling WinCreate- 
MsgQueue) belongs only to the main thread; it cannot be shared by 
another thread. A second thread, therefore, does not have a message 


VOID FAR 
/* 

Not 


PrintThread (VOID) 


e: This routine prints the current contents of the file buffer. It 

s as a separate thread that is concurrent with the mam application 
ead. 


register int i; 

BFILE HPrinter; 
USEORT BytesWritten; 
USEORT Action; 

DosOpen 

("PRN", 

ScHPrinter, 

&Action, 

OL, 

0 , 

1 , 

0x41, 

OL) ; 


/* Loop counter. 

/* Handle to printer. 

/* Receives number of bytes printed. 
/* Receives action taken by 'DosOpen', 

/* Open the printer. 

/* Printer file name. 

/* Receives printer handle. 

/* Receives action taken; n/a. 

/* New file size; n/a. 

/* File attribute; n/a. 

/* Open flags; open if file exists. 
/* Open mode; share/write only. 

/* Reserved; must be 0. 


/* Print all lines in the file buffer, 
for (i = 0; i <= LastLine; ++i) 

/* Test flag for aborting print routine, 
if (AbortPrint) 
break; 


/* Write a single line. 

DosWrite 

(HPrinter, 

LineTable [i].LineAddress, 
LineTable [i].LineLength-1, 
&BytesWritten); 


/* File handle. 

/* Address of source buffer. 

/* Number of bytes to print. 

/* Receives num. bytes written. 


/* write terminating carriage-return character. 


DosWrite 

(HPrinter, 


ScBytesWritten) ; 


/* File handle. 

/* Address of source buffer. 

/* Number of bytes to print. 

/* Receives num. bytes written. 


/* Close the printer. 

DosClose (HPrinter); 

/* clear the semaphore to restore access to file buffer to main thread. 
DosSemClear (&Sem); 

/* Terminate the print thread. 

DosExit (EXIT_THREAD,0); 

} /* end PrintThread */ 


9 Figure 12.4: 

The function PrintThread 
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DosExit 

Purpose: 

Terminates either a single thread or an entire process. 

Prototype: 

VOID APIENTRY DosExit 

(ushort f Terminate, Terminate flag; if assigned 

EXIT_THREAD, only the current 
thread is terminated; if assigned 
EXITJPROCESS, all threads in the 
application are terminated. 

ushort usExitCode) ; The thread or process exit code. 

Return Value: 

This function does not return. 


• Figure 12.5: 

The DosExit OS/2 function 

queue unless it explicitly calls WinCreateMsgQueue to create its own. 
If a new thread does not own a message queue (such as the thread that 
executes PrintThread in the example), it cannot call a Presentation 
Manager function that creates a window (such as WinCreateMsg¬ 
Queue) or sends a message (such as WinSendMsg); nor can it call a 
Presentation Manager function that indirectly causes a message to be 
sent (such as WinSetFocus). See the Presentation Manager documenta¬ 
tion for a current list of the functions that may not be called from a 
queueless thread. 

Note that if a new thread creates a message queue and a window, it 
can send and receive Presentation Manager messages; messages are one 
of the forms of communication among separate threads discussed in the 
next section. 

Standard C library functions are also off-limits for a new thread. 
There are two problems with these functions. First, a standard C library 
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function generally includes a stack-checking routine at the beginning of 
the code. This routine expects the function stack to be located in the nor¬ 
mal stack area of the automatic data segment; as you have seen, how¬ 
ever, the stack for a new thread is typically located either in the 
program's data area or in a separate segment dynamically allocated 
through the DosAllocSeg function. Accordingly, the stack-checking 
routine will abort the program. Remember that stack checking for any 
function that you write is turned off through the /Gs option normally 
used when compiling a Presentation Manager application (this flag was 
described in Chapter 2). 

The second problem with standard C library functions is that most of 
them can be called by only one thread at a given time (such functions 
are termed nonreentrant). Therefore, if the code executed by the main 
thread contains calls to a library function such as sprintf, a function ex¬ 
ecuted by a second thread must not call this function, since both threads 
may attempt to execute the function at the same time. 

Because of these problems, the example program uses OS/2 Dos 
functions rather than C library functions for printing the file. Note, 
however, that Microsoft C version 5.1 now supplies a special set of 
library functions that can be executed simultaneously by multiple 
threads. See the compiler documentation for information on using these 
functions. 

The previous section discussed the possibility of starting two concur¬ 
rent threads that execute the same body of code (by making a second 
identical call to DosCreateThread before the thread started by the first 
call has terminated). If your program can perform such an action (the 
example program cannot), not only must you reserve a separate stack 
for each thread, but you must also appropriately declare all variables 
used by these threads. You should declare variables that are to be shared 
by all instances of a function as external data or as static data declared 
within the scope of the function. You should declare variables that are 
to be private for each instance as automatic data (data declared within 
the function that are not static; these data are located within the stack, 
which is distinct for each thread). 
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COMMUNICATING 

• BETWEEN THREADS 

In general, when two or more threads use or manipulate the same 
program object, the threads must synchronize their activities to prevent 
conflicts. For example, two threads should not attempt to update the 
same section of a file at the same time; nor should they simultaneously 
try to read and increment a program counter. Also, separate threads 
commonly need to communicate while sharing a common task. For ex¬ 
ample, one thread may fill a buffer with data, while another thread 
processes these data; the first thread may have to notify the second 
thread when the buffer contains valid data. 

Implementing the print routine described in this chapter requires 
communication between the two program threads to achieve the fol¬ 
lowing four purposes: 

• The program must prevent modification of the file buffer while 
the buffer is being printed. 

• The program must not start another print routine thread while a 
print thread is already active. 

• The program must not free the Presentation Manager heap while 
it is being accessed by the print routine. 

® The main thread must be able to signal the print routine to abort. 

The first three purposes are achieved using an OS/2 semaphore, and 
the last is accomplished with a global program variable. This section 
discusses using semaphores and global variables within the context of 
the example program. It then describes the use of messages as a form 
of communication between separate program threads. 


Using Semaphores 
and Global Variables 

A semaphore is a program flag used to communicate simple 
"stop" and "go" information between separate threads or processes. A 
semaphore can be in one of two states: clear, generally indicating that a 
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thread should proceed, and set, indicating that a thread should stop and 
possibly wait for some event. OS/2 provides a large collection of func¬ 
tions for creating and managing semaphores; this section discusses 
three of these functions: DosSemSet, DosSemClear, and DosSemWait. 
Rather than providing a general explanation of the use of semaphores, 
this section describes specifically how semaphores are used to imple¬ 
ment the print routine within the example program. 

First, the example program creates a semaphore by making the fol¬ 
lowing external declaration at the beginning of the code (outside the 
scope of a function): 

ULONG Sem = 0; 

Such a semaphore, declared within your program, is known as a RAM 
semaphore (OS/2 also provides system semaphores, which are created 
and stored internally by the system and are more easily shared among 
separate processes). Note that the semaphore is assigned a value of 0, 
which places it initially in the clear state. 

Whenever the user selects the Print command, the print routine 
(the ID_PRINT case of the function Command, listed in Figure 12.3) 
sets the semaphore Sem immediately before starting the thread that 
prints the file. The semaphore is set through the following call to Dos¬ 
SemSet (Figure 12.6): 

DosSemSet (&Sem); 

The parameter passed to DosSemSet is the handle of the semaphore, 
which for a RAM semaphore is simply the far address of the semaphore 
(note that the compiler automatically converts the near address &Sem 
to a far address, since this parameter is declared as a far pointer). 

Immediately before the print thread terminates, the function Print- 
Thread (listed in Figure 12.4) clears the semaphore by calling DosSem- 
Clear (Figure 12.7), as follows: 

DosSemClear (&Sem); 

Since these two function calls are the only points in the example pro¬ 
gram where the semaphore is either set or cleared, the semaphore is in 
the set state only while the print routine is active. Accordingly, the other 
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DosSemSet 

Purpose: 

Sets the specified semaphore. 

Prototype: 

USHORT APIENTRY DosSemSet 

(hsem hsem) ; Semaphore handle; for a RAM semaphore, 
this parameter should be the far address of 
the semaphore; for a system semaphore, the 
parameter should be the handle returned by 
DosCreateSem or DosOpenSem. 

Return Value: 

Zero if the function was successful, or one of the following 
nonzero error codes if an error occurred: 

ERROR_EXCL_SEM_ALREADY_OWNED 
ERRORJNVALIDJHLANDLE 
ERROR_TOO_MANY_SEM_REQUESTS 

Related Functions: 

DosSemCiear (Figure 12.7) 

DosSemWait (Figure 12.8) 


® Figure 12.6: 

The DosSemSet OS/2 function 


parts of the code can test this semaphore to determine whether the print 
routine is currently executing. The program tests the semaphore in 
three different situations. 

First, before the program issues any instructions that modify the file 
buffer, it tests the state of the semaphore. If the semaphore is set, the 
modification is not performed. (Attempting to modify the file buffer while 
its contents are being printed could result in printing erroneous data.) The 
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DosSemClear 

Purpose: 

Clears the specified semaphore. 

Prototype: 

USHORT APIENTRY DosSemClear 

(hsem hsem) ; Semaphore handle; for a RAM semaphore 

this parameter should be the far address of 
the semaphore; for a system semaphore, the 
parameter should be the handle returned by 
DosCreateSem or DosOpenSem. 

Return Value: 

Zero if the function was successful, or one of the following 

nonzero error codes if an error occurred; 

error_excl_sem_already_owned 

ERROR_INVALID_HANDLE 

Related Functions: 

DosSemSet (Figure 12.6) 

DosSemWait (Figure 12.8) 


m Figure 12.7: 

The DosSemClear OS/2 function 

semaphore is tested at these points in the code by calling the function 
DosSemWait (Figure 12.8), as follows: 

USHORT Result; 


Result = DosSemWait 
(&Sem, 

OL) ; 
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DosSemWait 

Purpose: 

Waits, if necessary, for the specified semaphore to be cleared, 
or until the given timeout has elapsed. 

Prototype: 

USHORT APIENTRY DosSemWait 

(hsem hsem, Semaphore handle; for a RAM semaphore, 

this parameter should be the far address of 
the semaphore; for a system semaphore, the 
parameter should be the handle returned by 
DosCreateSem or DosOpenSem. 

LONG lTimeOut ) ; Specifies the maximum time to wait for the 
semaphore to clear; if this parameter is 0, the 
function returns immediately, returning 0 if 
the semaphore was clear or the nonzero 
value ERROR_SEM_TIMEOUT if the 
semaphore was set; if this parameter is given 
the value -1, the function waits indefinitely 
for the semaphore to clear. 

Return Value: 

Zero if the semaphore was cleared; ERROR_SEM_TIMEOUT 
if the semaphore was not cleared by the time the specified 
timeout expired; or one of the following nonzero error codes 
if an error occurred: 

ERROR_EXC L_SEM_ ALRE AD Y_0 WNED 
ERROR INTERRUPT 
ERRORJNVALIDJHANDLE 

Related Functions: 

DosSemClear (Figure 12.7) 

DosSemSet (Figure 12.6) 

• Figure 12.8: 

The DosSemWait OS/2 function 
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The first parameter to DosSemWait is the semaphore handle, as ex 
plained previously. The second parameter is the timeout flag; since this 
parameter is assigned 0, DosSemWait will not wait. Rather, it returns 
immediately, passing back a value indicating whether the semaphore is 
set or clear A zero return value indicates that the semaphore is clear, 
and a nonzero value indicates that it is set (or that an error occured; the 
examples in this chapter, however, do not test for error codes and simp¬ 
ly assume that a nonzero return code indicates that the semaphore is 
set). Such tests for the state of the semaphore are placed at the begin- 
flings of the following functions or routines. 

1. The function Character, which processes keystrokes that have 
character codes. 

2. The VK_DELETE and VK_F9 routines within the function Virt- 
Key, which process the Del key and the F9 key. 

3 The ID_PASTE routine within the function Command, which ex¬ 
ecutes the Paste command of the Edit menu by inserting the clip- 
board data into the file. 

4. The routine that processes the New file command in the 
ID_NEW case of the function Command. 

5. The routine that processes the Open file command in the 
ID_OPEN case of the function Command. 

If the semaphore is set, routines 1 and 2 warn the user by sounding the 
speaker, and return without performing the file modification, as follows: 

if (Result) 

{ 

WinAlarm (HWND_DESKTOP, WA_ERROR); 
return TRUE; 

} 

Routines 3, 4, and 5 warn the user by displaying a message box, 
and then return without performing the requested operation. For 
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example, the paste routine contains the following statements immedi¬ 
ately after the call to DosSemWait: 

if (Result) 

{ 

WinMessageBox 

(HWND_DESKTOP, 

HFrame, 

"Cannot Paste into File\n" 

"Print Routine in Progress", 

"PM Text Editor", 

0 , 

MB_OK j 

MB__ICONASTERISK) ; 

return FALSE; 

1 


The second primary use for the semaphore is to prevent the program 
from starting a second instance of the print function, PrintThread, 
while this function is already active. Accordingly, the ID_PRINT routine 
listed in Figure 12.3 issues the following statements before calling Dos- 
CreateThread to start the new thread: 


Result = DosSemWait 
(&Sem, 

0L) ; 

if (Result) 

{ 

WinMessageBox 

(HWND_DESKTOP, 

HFrame, 

"Print Routine Already in Progress", 
"PM Text Editor", 

0 , 

MB_OK | 

MB_ICONASTERXSK) ; 
return FALSE; 

} 
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The third and final use for the semaphore within the example pro¬ 
gram is to prevent the user from terminating the program while the 
print thread is still active. Terminating the program while the print 
thread is active not only would interrupt the print job, but also would 
probably result in a protection fault. Remember that the termination 
routine (the function Quit) first calls WinDestroyHeap to release the 
heap memory; if the print thread subsequently attempts to access this 
memory, the system immediately terminates the program with a 
protection fault message. 

To prevent a program exit while the print thread is still active, e ex¬ 
ample program provides a function (Close, listed in Figure 12.9) to 


MRESULT EXPENTRY Close (HWND hwnd, USHORT msg, MPARAM mpl, MPARAM 


{ 

USHORT Reply; 
USHORT Result? 


/* Response from message box. 

/* Return code from DosSemWait. 


mp2) 


*/ 

*/ 


/* Determine if print 
Result = DosSemWait 
(&Sem, 

0L) ; 

if (Result) 


routine is busy. 

/* Test print semaphore. 

/* RAM semaphore handle. 

/* Timeout: return immediately. 
/* Print routine active. 


Reply = WinMessageBox /* Query user whether to abort print 
(HWND_DESKTOP, 

hwnd, , . _ . . 

"Print Routine in Progress\nAbort Print. , 

"PM Text Editor", 


*/ 

*/ 

V 

V 

*/ 

*/ 


U/ , 

MB_YESNO | 
MB_ICONQUESTION)? 
if (Reply == MBID_YES) 

{ 

AbortPrint = TRUE; 


/* User wants to abort. / 

/* set global flag to stop print routine. */ 


/* Wait until print 
DosSemWait 
(&Sem, 

-1L) ? 

} 

else 

return FALSE; 


thread clears the semaphore before ending.*/ 
/* RAM semaphore handle. _ 

/* Timeout: don't return until clear. / 


} 

WinPostMsg 
(hwnd, 
WM_QUIT, 
0L, 

0L) ? 


/* End program by posting WM_QUIT message. 
/* Recipient window: client. 

/* Message ID. 

/* mpl: n/a. 

/* mp2: n/a. 


} /* end Close */ 


® Figure 123: 

The function Close of the example program 
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process the WM_CLOSE message (Figure 12.10). The WM_CLOSE mes¬ 
sage is sent to the client window when the user selects the Close item 
from the system menu or double-clicks the mouse on the system menu 
icon. Processing this message allows your program to perform any re¬ 
quired final tasks before the window is destroyed and the application is 
terminated; this message also gives your program the opportunity to 
prevent ending the program. 

If you pass the WM^CLOSE message to the system for default 
processing (by calling WinDefWindowProc), the system causes the 
program to terminate by posting (that is, placing in the message queue) 
the WM^QUIT message (Figure 2.10). If your program processes this 


WM_CLOSE 

Purpose: 

This message is sent by the system to the client window 
when the user selects the Close item from the system menu 
or double-clicks the mouse on the system menu icon. 

Parameters: 

MPARAM mpl NULL. 

MPARAM mp2 NULL. 

Return Value: 

NULL. 

Notes: 

The default processing for this message (performed by Win- 
DefWindowProc) is to terminate the application by posting 
the WM_QUIT message to the window's message queue. If 
your application processes this message, it can post 
WM_QUIT or call WinDefWindowProc to terminate the 
program, or simply return NULL to prevent terminating 
the program. 


® Figure 12.10: 

The WM_CLOSE Presentation Manager function 
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message, however, you can either post the WM_QUIT message to ter¬ 
minate the program, or simply issue a return statement to allow the 
program to continue. 

In response to the WM_CLOSE message, the function Close first tests 
the semaphore, as explained above, to determine whether the print 
thread is active. If the thread is not active, the function proceeds to ter¬ 
minate the program by posting the WM_QUIT message. The message is 
posted by calling the WinPostMsg function (Figure 12.11), as follows: 


WinPostMsg 

(hwnd, 

/* Recipient window: client. 

*/ 

*/ 

WM_QUIT, 

/* Message ID. 

0L, 

/* mpl: n/a. 

*/ 

0L) ; 

/* mp2: n/a. 

*/ 


Note that WinPostMsg, in contrast to WinSendMsg, places the mes¬ 
sage in the target window's message queue rather than directly invok¬ 
ing the window procedure. As described in Figure 2.10 and explained 
in Chapter 2, the WM_QUIT message causes WinGetMsg to return a 
value of FALSE, which terminates the main message loop and ends the 
program. 

If the print thread is currently active, the Close function displays a 
message box asking the user whether the print job should be ter¬ 
minated. If the user chooses not to terminate. Close simply issues a 
return statement, which causes normal processing to resume (no 
WM_QUIT message is posted). 

If, however, the user decides to abort the print routine and end the 
program. Close first sets the global flag AbortPrint to TRUE. As you 
can see in Figure 12.4, the PrintThread function tests this flag with each 
pass of the loop that prints the lines of the file; if it finds that AbortPrint 
is TRUE, it immediately exits from the printing loop, closes the printer, 
clears the semaphore, and terminates the thread. AbortPrint is an ex¬ 
ample of a shared memory location used to communicate information 
between threads. External memory variables can be easily shared 
among threads, since all program threads have equal access to the 
memory segments owned by the process in which they run. (As men¬ 
tioned in Chapter 1, OS/2 also provides functions that allow separate 
processes to share memory segments; shared memory is an important 
form of interprocess communication.) 
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WinPostMsg 

Purpose: 

Posts a message to the message queue belonging to the 
specified window. 

Prototype: 

BOOL APIENTRY WinPostMsg 
(hwnd hwnd / Handle of the target window. 

USHORT msg, The identifier of the message that is being 

sent. 

mparam mpi , The first message parameter; the meaning is 

specific to the message. 

mparam mp2 ) / The second message parameter; the meaning 
is specific to the message. 

Return Value: 

TRUE if the function was successful, or FALSE if an error 
occurred. 

Notes: 

WinPostMsg places the message in the target window's 
message queue and returns immediately (in contrast, Win- 
SendMsg calls the target window procedure directly, and 
does not return until this procedure has terminated). Accord- 
WinPostMsg does not return the result of the message 
processing, but only an error code indicating whether the 
message was successfully posted to the queue. 

Related Functions: 

WinSendMsg (Figure 4.8) 

• Figure 12.11: 

The WinPostMsg Presentation Manager function 




Exploiting Multitasking and Interprocess Communication 605 


After Close has set AbortPrint to TRUE to end the print routine, it 
does not directly proceed to terminate the application. Rather, it first 
waits until PrintThread has successfully ended (it cannot assume that 
PrintThread ends immediately). To make sure that PrintThread has 
ended, it again calls DosSemWait, this time passing a timeout value of 
-1L, which causes DosSemWait not to return until the semaphore has 
been cleared. The call to DosSemWait is as follows: 

DosSemWait 

(&Sem, /* RAM semaphore handle. */ 

-1L); /* Timeout: don't return until clear. */ 

Note, therefore, that DosSemWait can be used not only to test the value 
of a semaphore, but also to cause the program to pause until the 
semaphore is dear. Also, if you set the timeout parameter to a value 
greater than 0, the function will wait until either the semaphore has be¬ 
come clear or the specified timeout period has elapsed. 

You should make one final change in the text editor program to im¬ 
plement the print routine. Note that the user can also terminate the pro¬ 
gram by selecting the Exit item from the File submenu, as well as 
through the Close item of the system menu. The routine that handles 
the Exit command in the prior version of the example program (listed m 
Figure 8.38, in the ID_EXIT case of the function Command) directly 
calls the Quit function, which immediately aborts the program. Since 
this tactic would bypass the test for an active print thread, the routine 
should instead pass control to the code that handles the WM_CLOSE 
message, as follows: 


case ID__EXIT: 

WinSendMsg 

(hwnd, 

WM_CLOSE, 

0L, 

0L) ; 


return FALSE; 
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Using Messages 

Semaphores and shared memory are traditional forms of inter¬ 
process communication available to all OS/2 protected mode 
programs. Presentation Manager programs can also use messages as a 
form of communication among separate threads. To be able to send and 
receive messages, each thread must create at least one window; the 
threads can then exchange messages using the standard Presentation 
Manager functions WinSendMsg and WinPostMsg. Note that message 
identifiers are not limited to the predefined messages that have been 
described in this book, but can also be programmer-defined messages 
that are recognized only by the threads involved in the exchange. 

The following are the specific steps you can use to establish message 
communication between the main program thread and a new thread 
begun by calling DosCreateThread: 

1. The new thread should call WinCreateMsgQueue (Figure 2.3) to 
create a message queue. Note that the new thread does not have 
to call Winlnitialize; rather, it can pass the anchor block handle 
obtained by the main thread (Winlnitialize need be called only 
once by a given process). 

2. The new thread should then call WinRegisterClass (Figure 2.4) 
to register a window class, passing the name of the window pro¬ 
cedure that will process the messages sent to the window belong¬ 
ing to the window it creates. 

3. The new thread can call the Presentation Manager function Win- 
CreateWindow (Figure 12.12) to create an object window. An ob¬ 
ject window is one that is not displayed on the screen, does not 
receive input messages, and has no parent; an object window, 
however, can serve as a vehicle for receiving messages from 
other windows. To create an object window, you should pass 
WinCreateWindow the identifier HWND OBJECT as the handle 
of the parent window (the first parameter), and the address of 
the window procedure as the second parameter. The remaining 
parameters should all be 0. 
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4. Since the newly created window is an object window, it does not 
have to process WMJPAINT or other system messages (any sys¬ 
tem messages it receives can simply be passed to the WinDef- 
WindowProc function for default processing). Rather, it can 
focus on processing the programmer-defined messages sent by 
other windows. 


Note that the identifiers for programmer-defined messages should 
have values equal to or larger than the value WMJUSER. For example, 
you could define a set of programmer-defined messages as follows: 

#define WM_PRIVATE_00 (WMJJSER + 0) 

#define WM_PRIVATE_01 (WMJJSER + X) 

#define WM_PRIVATE_02 (WMJJSER + 2) 

Note that using messages as a form of private communication be¬ 
tween program threads represents the third major use for Presentation 
Manager messages discussed in this book. To summarize, the book has 
discussed the following three purposes served by the Presentation 
Manager message mechanism: 

@ Messages are the primary channel through which the program 
receives input and is informed of significant events. 

e By sending messages to system window procedures, the applica¬ 
tion can control these windows and receive important system 
services. The predefined messages described in this book thus 
form a significant extension to the application program interface 
accessed through the system functions (Win, Gpi, Dos, and 
others). 

® Messages can serve as a private channel of communication be¬ 
tween separate program threads. 
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WinCreate Window 

Purpose: 

Creates a new window. 


Prototype: 

HWND APIENTRY WinCreateWindow 

(HWND hwndParent, 

The handle of the parent 
window; the value ■ 

HWND_DESKTOP indicates 1 

the desktop window and j 

creates a top-level window; the 
value HWND_OBJECT creates 
an object window (which has 
no parent). 

PSZ pszClass, 

Address of a string containing 
the name of the window class. 

PSZ pszName, 

Address of the window text, or 
other class-specific data. 

ULONG flStyle, 

The window style. 

SHORT x, 

The horizontal window 
position relative to the origin 
of the parent window. 

SHORT y, 

The vertical window position 
relative to the origin of the 
parent window. 

SHORT cx, 

The window width. 

SHORT cy, 

The window height. 

HWND hwndOwner, 

Handle of the owner window. 

HWND hwndlnsertBehind, 

Handle of the sibling window 
behind which the specified 
window is placed; the value 

HWND TOP places the j 

window on top of all siblings, 
and HWND BOTTOM places 
it on the bottom. 

USHORT id, 

The window identifier. 


® Figure 1212: 

The WinCreate Window Presentation Manager function 
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Address of a buffer containing 
class-specific data; this address 
is passed to the window 
procedure by the 
WM_CREATE message (Figure 
3.16). 

A reserved field that must be 
zero. 

Return Value: 

The handle of the newly created window, or the value NULL 
if an error occurred. 

Related Functions: 

WinCreateStdWindow (Figure 2.5) 


• Figure 1212: 

The WinCreate Window Presentation Manager function (continued) 


PVOID pCtlData, 


PVOID pPresParams); 
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his glossary defines many of the terms you may en¬ 
counter while working with the Presentation Manager. 
If a term has a special meaning within the context of 
OS/2 or the Presentation Manager, this definition is 
given rather than the general significance of the word. Note also that 
OS/2 is a new and rapidly evolving operating system; you may there¬ 
fore discover inconsistencies in the terminology from one source to 
another, as well as general changes over time in the usage of these tech¬ 
nical terms. 


accelerator A keystroke that sends a command message 
(WM_COMMAND) directly to the client window; it can be used as a 
shortcut for issuing a menu command. Accelerators are defined within 
a table stored as a program resource and loaded by the WinCreateStd- 
Window function. 

active application The application that currently owns the active 
window. 


active window The top-level window that the system places on 
top of all other top-level windows; the active window, or one or its des¬ 
cendants, owns the keyboard focus. 

alias A segment descriptor that references the same memory seg¬ 
ment as another descriptor. 

anchor block handle A numeric value that identifies a process to 
the Presentation Manager (returned by Winlnitialize). 

ANSI American National Standards Institute. ANSI codes are a set 
of escape sequences that can be embedded in video output to control 
the console. 


API The application program interface, which is a set of services 
provided by OS/2 and the Presentation Manager for application 
programs. 
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argument A value passed to an operating-system command from 
the command line, or passed to a function within a program; same as 
parameter. 

ASCII American Standard Code for Information Interchange; the 
encoding scheme that represents the character set used by micro¬ 
computers. 

asynchronous Two or more procedures are said to be asyn¬ 
chronous if they occur concurrently, but without timing relationships. 
Specifically, if two procedures are asynchronous, when a particular in¬ 
struction is executed in one procedure it is impossible to predict which 
instruction is currently being executed in the other procedure. See also 
synchronous. 

atomic Indivisible; describes a sequence of processor operations 
that cannot be interrupted, typically those required to execute a single 
machine instruction. 

automatic data segment The segment containing a program's 
initialized, uninitialized, and constant data, as well as the program 
stack and heap. 

automatic variable A C program variable declared within the 
scope of a function, without using the static or extern keyword; auto¬ 
matic variables are private to each instance of a function, and are stored 
within the function's stack frame or machine registers. 

background programs Programs executed through the RUN 
configuration command, the DETACH command-line instruction, or 
from a parent program. These programs are not attached to a screen 
group and do not normally interact with the user. 

batch file A file containing a sequence of instructions to be ex¬ 
ecuted by a command interpreter; these files have the .BAT extension in 
the real mode, and the .CMD extension in the protected mode. 
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BIOS Basic input-output system; the low-level code that controls 
I/O devices, normally implemented in the read-only memory (ROM) 
supplied with the computer. 

bitmap A data structure contained in a file or in memory that stores 
a graphic image as a sequence of on or off bits indicating the actual 
pixel values used to create the image on the screen; see also metafile. 

block To wait for an event without consuming processor cycles. For 
example, a thread can block while waiting for an event, and it will be 
released by the operating system when the event occurs. 

boot disk The disk drive that contains the code used to initialize 
the computer and load the operating system when the system is first 
reset or powered on. 

bound program Same as dual-mode program. 

buffer An area in memory used to temporarily store data that is 
read or written in blocks; used to increase the efficiency of data-transfer 
operations. 

busy waiting Creating a delay, or waiting for a computer event, by 
executing a nonproductive program loop. 

cache A high-speed storage area used to improve the efficiency of 
accesses to a slower-speed storage medium. For example, temporarily 
storing data in a disk cache in random access memory can reduce the 
number of accesses required to transfer contiguous blocks of disk data. 

cache presentation space A presentation space supplied from 
the system's internal collection of presentation spaces; this form of 
presentation space can be supplied quickly and without allocating ad¬ 
ditional memory. See presentation space. 

call gate A special type of segment descriptor that allows a process 
to call a subroutine contained within a higher-privileged segment. 
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capturing the mouse Issuing a function call (WinSetCapture) 
that causes all subsequent mouse messages to be sent to the issuing 
window regardless of the mouse pointer position on the screen (other¬ 
wise, mouse messages are sent to the window that underlies the 
pointer). 

caret Same as cursor. 

cascade To arrange windows in an overlapping fashion (the Presen¬ 
tation Manager default arrangement); see also tile. 

CGA Color graphics adapter; a standard video controller that 
provides graphics with a maximum resolution of 640 by 200 pixels. 

character code A hardware-independent code received by an ap¬ 
plication when the user presses a character key; usually, it is the ASCII 
value of the keystroke. See also scan code and virtual-key code. 

check box A control window consisting of a small square and an as¬ 
sociated text label, typically contained within a dialog box. Check boxes 
are normally displayed within groups, which allow the user to select zero 
or more items. When selected, a check box contains a check mark. 

child process A process started by another process (its parent). 

child window A window that is displayed within the boundaries 
of another window (its parent). 

class A set of attributes, including the address of a window proce¬ 
dure, that define the behavior of a window. A class is registered through 
the WinRegisterClass function, and every window must be assigned to 
a class when it is created. A window is known as an instance of the class 
to which it belongs. 

click To rapidly press and release a mouse button. 

client window The window created by WinCreateStdWindow 
that is typically managed by the application program and used to dis¬ 
play program data; it is a child of and is owned by the frame window. 
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clip To eliminate data written to the screen or other device that falls 
outside of a given boundary. 

clipboard A Presentation Manager facility for transferring data 
within a single application or among separate applications. 

code page A table used to define a character set used by the system. 

command processor A program that executes operating-system 
commands typed at a prompt. By default, the command processor for 
protected mode screen groups is CMD.EXE, and for the real mode 
screen group it is COMMAND.COM. 

compatibility box The OS/2 screen group for running real mode 
MS-DOS programs. 

concurrency The simultaneous execution of two or more sequen¬ 
ces of machine instructions; see also multitasking. 

control window A window used to receive input or perform a 
specific function; for example, a scroll bar owned by the frame window, 
or a push button owned by a dialog box. Control windows typically 
send messages to their owners to report user input or other relevant 
events. 

cooked mode A state of a character device driver in which it 
processes certain characters within the data stream as control codes; 
also known as the ASCII mode. See also raw mode. 

copy To transfer a selected block of data from an application into the 
clipboard, leaving the program data intact; see also cut and paste. 

CPU The central processing unit, or the microprocessor belonging to 
a microcomputer. 

critical section A body of code accessing a program object (such as 
a memory location) that cannot be shared by more than one simul¬ 
taneous task. 
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cursor A highlighted area that marks a particular character position 
on the screen, typically indicating the point at which new characters are 
inserted into the textual data displayed on the screen. 

cut To remove a selected a block of data from an application and 
place it into the Presentation Manager clipboard; see also copy and paste. 

deadlock A situation in which one or more tasks is blocked, waiting 
for an event that cannot occur. 

descriptor A structure in memory maintained by the operating sys¬ 
tem, which contains the physical address of a segment as well as other 
information regarding this segment. 

descriptor table A table in memory containing a collection of seg¬ 
ment descriptors. 

desktop window The entire Presentation Manager screen, which 
is the parent of all top-level windows. 

device context The physical device associated with a presentation 
space. See presentation space. 

device driver A program that translates operating-system com¬ 
mands into the device-specific code necessary to control a given device. 

dialog box A temporary Presentation Manager window that con¬ 
tains a set of control windows for displaying data and obtaining infor¬ 
mation from the user. 

dialog-box procedure The function that processes the messages 
sent to a dialog box; analogous to a window procedure, which pro¬ 
cesses the messages sent to an application window (usually the client 
window). 

DOS compatibility box Same as compatibility box. 

double-click To click a mouse button twice in rapid succession, 
while the mouse pointer remains in the same screen area. 
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drag To press a mouse button and hold the button down while 
moving the mouse. 

dual-mode program A specially prepared program that can run 
under MS-DOS, in the compatibility box of OS/2, or within a protected 
mode screen group; the same as a bound program. 

dynamic linking Linking to a function in a dynamic-link library. 

dynamic-link library A file (with the .DLL extension) containing 
functions that can be loaded into memory and called by one or more 
OS/2 programs; a dynamic-link library can also store resources that can 
be accessed by OS/2 programs. 

EBCDIC Extended binary-coded decimal interchange code; an 
8-bit code for character representation, typically used on IBM minicom¬ 
puters and mainframes. 

edit control A control window, typically contained in a dialog box, 
that allows the user to enter text. 

EGA Enhanced graphics adapter; a standard video controller that 
provides graphics with a maximum resolution of 640 by 350 pixels. 

event-driven process A process that blocks until it is activated 
by an external event. 

exception A processor error or other internal condition that 
generates an interrupt and transfers control to a software routine 
designed to handle the event. 

expanded memory Memory available to real mode programs 
above the normal 640-kilobyte limit. This memory is contained on 
special adapter cards and is accessed through a hardware paging 
mechanism. 

Extended Edition A version of OS/2 that contains operating-sys¬ 
tem extensions such as a database manager and a communications 
manager. 
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extended memory Memory contained in 80286/80386 machines 
at addresses above 1 megabyte. This memory space can be directly ac¬ 
cessed only in protected mode. 

external variable A C program variable declared outside the 
scope of an individual function. 

Family API A subset of the OS/2 API functions that can be called 
by dual-mode programs when they are running in real mode. 

far address An address containing both a 16-bit segment selector (in 
the protected mode, or the address in the real mode) and a 16-bit offset 
within this segment. See also near address. 

focus window The window to which the system sends all key¬ 
board messages. 

font A collection of bitmaps defining the shape of each character 
within a given character set. 

frame window The top-level window created by WinCreateStd- 
Window, which owns and is the parent of the other windows generated 
by this function. 

gigabyte 2 30 , or approximately one billion, bytes. 

global descriptor table A table maintained in memory contain¬ 
ing the descriptors for segments that can be accessed by all processes; 
see also local descriptor table. 

handle A numeric value returned by many OS/2 and Presentation 
Manager functions used to identify the owner of a program object (such 
as an open file or a window) when subsequent function calls are made. 

heap A block of memory out of which smaller blocks of memory are 
dynamically allocated. 

hotkey The keystroke that activates a background program (under 
OS/2, usually a monitor). 



Glossary 619 ® 


hot Spot A single, specially designated pixel within a mouse 
pointer; the position of the mouse pointer is specified as the coordinates 
of the hot spot. 

huge memory allocation A block of allocated memory consist¬ 
ing of more than one segment. The segments need not be contiguous in 
memory, but the selectors for these segments differ numerically by a 
constant amount. 

icon A fixed-size graphic image that you can create and display 
within a Presentation Manager application; an application window is 
represented by an icon when it is minimized. 

import library A library file that resolves references to dynamic- 
link functions by supplying records that contain the module name and 
entry point for the function, but not the actual code. 

interprocess communication Sending signals or exchanging 
data among separate threads or processes. 

interrupt A software, hardware, or processor-generated event that 
passes control to a routine in memory that provides a service or handles 
a condition. 

interrupt routine The device driver entry point invoked by 
hardware interrupts that are generated by the associated device, see 
also strategy routine. 

invalidate To add a section of a window to its update region , which 
is the area of the window that must be redrawn during processing of 
the WM_PAINT message. 

I/O privilege Permission granted to a specific code segment to 
issue direct port I/O instructions or to enable or disable hardware inter¬ 
rupts (under OS/2, a segment with I/O privilege runs at privilege 
level 2). 
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kernel The core operating-system code that operates at the highest 
privilege level; also, the portion of the API exclusive of the Presentation 
Manager and other operating-system extensions. 

kernel application A program not written specifically for the 
Presentation Manager. 

kilobyte 2 10 , or 1024, bytes. 

list box A rectangular control window (typically belonging to a 
dialog box) that contains a vertical scroll bar and is used to display a list 
of strings. The user can scroll through the list of strings, and can select a 
given string. 

local descriptor table A table maintained in memory containing 
the descriptors for segments that can be accessed by a specific process; 
see also global descriptor table. 

maximize To enlarge a window to its maximum size, which fills 
most of the screen. 

maximize box A control window displaying an upward-pointing 
arrow; when the user clicks the mouse with the pointer within this con¬ 
trol, the owner (or parent) window is maximized. 

megabyte 2 20 , or approximately 1 million, bytes. 

menu A control window used to display a list of commands; the 
user issues a command by selecting the associated item from the menu. 

message queue A data structure associated with a Presentation 
Manager program thread, which is used to store messages posted to 
any of the windows created by that thread. 

metafile A data structure contained in a disk file or in memory that 
stores a graphic image as a sequence of Presentation Manager com¬ 
mands required to create the image; see also bitmap. 

minimize To reduce a window to an icon on the screen. 
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minimize box A control window displaying a downward-point 
ing arrow; when the user clicks the mouse with the pointer within this 
control, the owner (or parent) window is minimized. 

m odal Describes a dialog box that does not allow the user to switch 
the focus to another window owned by the same application, until the 
dialog box is dismissed. A system modal dialog box disallows the user 
from switching the focus to any other window in the system. 

monitor An OS/2 program that processes the stream of characters 
passing to or from a character device. 

mouse An input device that moves a pointer on the screen as it is 
moved on the desk surface; a mouse also has one to three buttons that 
transmit information to the program. 

multiprocessing Simultaneous execution of code by more than 
one processor in a single computer. 

multitasking Simultaneous execution of more than one sequence 
of machine instructions. 

multiuser Refers to a single computer connected to more than one 
terminal, which allows several users to share the same processor. Note 
that OS/2 is not a multiuser system. 

near address An address consisting of only a 16-bit offset. See also 
far address. 

object window A Presentation Manager window used to receive 
messages; an object window is not displayed on the screen, does not 
receive input messages, and does not have a parent. 

overcommitment (of memory) Allocation of more memory 
than is physically present in the machine; accomplished by swapping 
segments between memory and secondary storage on a disk. 
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parameter A value passed to an operating-system command from 
the command line, or passed to a function within a program; same as 
argument. 

parent process A process that starts another process (its child). 

parent window A window within which one or more child win¬ 
dows are displayed. 

paste To insert a block of data from the Presentation Manager clip¬ 
board into the data belonging to an application; see also cut and copy. 

path The full specification of the location and name of a disk file, in¬ 
cluding the drive, directory, and file name. 

pipe A form of interprocess communication that allows two related 
processes to exchange a serial stream of data. 

p ixel Picture element; smallest unit on the screen that can be control- 
led (turned on or off, or assigned a color or intensity). 

point To place the hot spot of the mouse pointer on a given item or 
within a given area. 

pointer A fixed-size graphic image that is moved on the screen in 
response to movements of the mouse, or in response to program func¬ 
tion calls. 

poll To test for the occurrence of a specific event; for example, an in¬ 
efficient program might repeatedly poll for the arrival of a character 
rather than blocking. 

port An input-output address that can be used to control a device. 

post To place a message in a Presentation Manager message queue. 

preempt To take control away from a particular task in a multitask¬ 
ing system (rather than letting the task voluntarily yield control). OS/2 
is a preemptive multitasking system. 
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Presentation Manager An operating-system extension provided 
with OS/2 versions 1.1 and later, which provides a windowed graphics 
interface similar to Microsoft Windows. 

Presentation Manager application A program written speci¬ 
fically for the Presentation Manager, which performs the necessary in¬ 
itializations and calls Presentation Manager API functions. 

presentation space The abstract space onto which a Presentation 
Manager application displays data; it must be associated with a physi¬ 
cal device (the device associated with a presentation space is known as 
the device context). A presentation space is maintained as a data struc¬ 
ture by the system, and it is assigned device-independent attributes, 
such as a current set of colors and a current font. 

priority A value assigned to each thread in the system that allows 
the scheduler to determine which thread among those ready to run 
should be dispatched. 

privilege The set of permissions associated with a particular seg¬ 
ment. There are four privilege levels, numbered from 0 (the highest 
privilege level, reserved for the operating system) to 3 (the lowest privi¬ 
lege level, for application programs). 

process A single instance of the execution of a program. 

program A collection of code and data stored in an executable file 
and loaded into memory at run-time. 

protect To prevent a given process from corrupting other processes 
in a multitasking system; OS/2 uses the hardware protection 
mechanisms provided by the 80286 processor. 

protected mode A processor state of the 80286/80386 processors 
that allows the operating system to safely run multiple tasks and pro¬ 
vide virtual memory; same as virtual inode. 
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protection fault A processor exception generated when an ap¬ 
plication attempts to violate the protection mechanisms enforced in the 
protected mode. See also exception. 

push button A small, rectangular control window with rounded 
corners and a text label that can be selected ("pushed") by the user to 
initiate an action. 

queue A form of interprocess communication provided by OS/2; 
specifically, an ordered collection of messages that have been sent from 
one or more processes to a single receiving process (not related to a 
Presentation Manager message queue). 

radio button A control window consisting of a small circle with an 
associated text label, typically displayed within a dialog box. Radio but¬ 
tons are usually placed in groups that allow the user to select only one of 
the items (that is, they are used for mutually exclusive choices); when a 
radio button is selected, the inside of the circle is highlighted. 

RAM Random access memory; the randomly addressable, volatile 
main memory used to store programs and data. 

raw mode A state of a character device driver in which it passes all 
characters as literal values, and does not respond to control codes embedded 
in the data stream; also known as binary mode. See also cooked mode. 

real mode A processor state of the 80286/80386 processors that 
emulates the operation of the 8086/8088 processors. 

real mode screen group Same as compatibility box. 

reentrant A body of code is reentrant if it can be executed more than 
once at a given time. 

resource A collection of read-only data stored within an executable 
file or in a dynamic-link library. These data are inserted directly into the 
file by a resource compiler, and they are loaded into memory when re¬ 
quired by an application. 



Glossary 625 




resource comp iler A utility that translates a text script into binary 
resource data, and inserts these data directly into an executable file. 

resource script A text file that defines a set of OS/2 resources. 

ROM Read-only memory; nonvolatile memory supplied with 
microcomputers that normally contains code to control hardware 
devices. 

scan code A hardware-specific code emitted by the keyboard to in¬ 
dicate the key that has been pressed or released; see also character code 
and virtual-key code. 

scheduler The portion of the operating system that apportions 
CPU time among multiple threads and determines the priority of each 
thread. 

screen group A collection of processes that share a single virtual 
screen, keyboard, and mouse. 

scroll To move a block of data displayed within a window toward 
one of the four window borders. 

scroll bar A control window used to scroll textual data within a win¬ 
dow. A horizontal scroll bar is typically located along the lower edge of its 
parent and scrolls text horizontally; a vertical scroll bar is typically located 
along the right edge of its parent and scrolls text vertically. 

segment A variable-length block of allocated memory together 
with a set of attributes (such as the privilege level). 

segment descriptor Same as descriptor. 

selector The virtual address of a memory segment, which serves as 
an index into a table containing the actual physical address, the selector 
is loaded into a segment register, such as DS, to address the correspond¬ 
ing segment. 
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semaphore A software flag used to synchronize the activities of 
two or more threads of execution. 

serialize To ensure that a given object can be accessed by only one 
thread at a time; access to an object is typically serialized by means of a 
semaphore. 

server The process that owns a queue and receives the queue messages, 
session The same as a screen group. 

session manager A system utility that manages switching among 
screen groups; if the Presentation Manager is installed, this function is 
performed by the Task Manager. 

sizing border A control window that forms a wide border around 
its parent window; it can be used to adjust the parent window size with 
the mouse. 

spooler A background program that stores printer output in tem¬ 
porary files and prints these files in a given order. 

stack A data structure in memory that holds the parameters and 
local variables belonging to a function while the function is active. It is 
also used for the temporary storage of register contents or memory vari¬ 
ables. Items placed on the stack are said to be pushed, and items 
removed are popped; items are stored within the stack on a last-in, first- 
out basis, and with Intel processors the stack grows downward in 
memory (that is, toward lower addresses) as values are pushed. 

strategy routine The device driver entry point called by the 
operating system to request a device service; see also interrupt routine. 

subsystem A set of dynamic-link functions that control a common 
resource, such as the OS/2 video-management functions that are 
named with the Vio prefix. 
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swapping The temporary storage of memory segments on disk to 
make room for other segments. This mechanism is useful when 
memory is over commit ted. 

synchronous Two procedures are said to be synchronous if their 
actions occur in a specific order. For example, if one procedure waits at 
a given point until a second procedure completes, these procedures are 
said to be synchronous. See also asynchronous. 

task A general term referring to one of the concurrent threads or 
processes of a multitasking system. 

thread The basic dispatchable entity under OS/2; the execution of a 
series of machine instructions within a program. 

tile To arrange windows in a side-by-side, nonoverlapping fashion; 
see also cascade. 

time slice The period of time that the scheduler allows a thread to 
run before it grants CPU time to another thread of equal priority. 

title bar A control window typically located along the top edge of 
its parent; the title bar contains a text title and is used for moving the 
parent window with the mouse. 

top-level window A window that is the direct child of the desk¬ 
top window; also known as a main window. 

TSR A terminate-and-stay-resident program under MS-DOS or the 
DOS compatibility box of OS/2. These programs remain loaded in 
memory while the user runs other applications in the foreground. 

typamatic Refers to the automatic repeated generation of key¬ 
strokes when a key is held down. 

Update region The invalid area of a window that must be updated 
by the routine that processes the WM_PAINT message. 
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VGA Video graphics array; a standard video controller that normal- 
ly provides a graphics resolution up to 640 by 480 pixels. 

virtual-key code A set of device-independent codes used to iden¬ 
tify keys that do not have standard character codes; for example, the 
function or arrow keys can be identified through virtual-key codes. See 
also character code and scan code. 

virtual memory The allocatable memory space in protected mode, 
which may exceed the amount of physical memory installed in the 
machine. Segments within this space may be temporarily swapped to a 
disk to make room for segments that are currently being referenced. 

virtual mode Same as protected mode. 

window The fundamental object owned by a Presentation Manager 
application, which can receive messages and is typically associated 
with a rectangular area on the screen used to interact with the user. 

window class See class. 

window procedure The function that processes the messages 
sent to a given window (when a message is sent, the system calls this 
procedure, passing the content of the message as parameters). 

word A two-byte data value; stored in memory with the low-order 
byte first (that is, at the lower address), followed by the high-order byte. 
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Ms appendix provides a brief alphabetical summary of 
the Presentation Manager and OS/2 functions that have 
been described in the book. The synopsis of each func¬ 
tion provides a short statement of the function's pur¬ 
pose, the function prototype, and a reference to the figure in the book 
that fully describes the function. Note that the inside book covers list 
these same functions according to the types of services they provide. 
Note also that the functions described in this book are a subset of the 
full set of services offered by OS/2 and the Presentation Manager; see 
the technical documentation cited in the Bibliography for information 
on functions not covered in the book. 

® DosAllocSeg 

Purpose: 

Allocates a memory segment. 

Prototype: 

USHORT APIENTRY DosAllocSeg 
(USHORT usSize, 

PSEL psel, 

USHORT fAlloc); 



Figure: 

9.1 

• DosCreateThread 

Purpose: 

Starts a new thread of execution within the current process. 
Prototype: 

USHORT APIENTRY DosCreateThread 

(VOID PASCAL FAR *pfnFunction (VOID), 

PTID ptidThread, 

PBYTE pbThrdStack); 
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Figure: 

12.1 

• DosExit 

Purpose: 

Terminates either a single thread or an entire process. 
Prototype: 

VOID APIENTRY DosExit 
(USHORT fTerminate, 

USHORT usExitCode); 


Figure: 

12.5 

• DosGetResource 

Purpose: 

Loads the specified resource segment into memory. 
Prototype: 

USHORT APIENTRY DosGetResource 
(HMODULE hxnod, 

USHORT idType, 

USHORT idName, 

PSEL psel); 


Figure: 

10.26 

• DosGetSeg 

Purpose: 

Secures access to a shared memory segment for the current 
process. 
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Prototype: 

USHORT APIENTRY DosGetSeg 
(SEL sel); 


Figure: 

9.7 

• DosSemClear 

Purpose: 

Clears the specified semaphore. 
Prototype: 

USHORT APIENTRY DosSemClear 
(HSEM hsem); 


Figure: 

12.7 

• OosSemSet 

Purpose: 

Sets the specified semaphore. 
Prototype: 

USHORT APIENTRY DosSemSet 
(HSEM hsem); 


Figure: 

12.6 

• DosSemWait 

Purpose: 

Waits, if necessary, for the specified semaphore to be cleared, 
or until the given timeout has elapsed. 
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Prototype: 

USHORT APIENTRY DosSemWait 
(HSEM hsem, 

LONG 1TimeOut); 


Figure: 

Figure 12.8 

• DosSizeSeg 

Purpose: 

Obtains the size in bytes of a specified memory segment. 
Prototype: 

USHORT APIENTRY DosSizeSeg 
(SEL selPULONG pulSize); 


Figure: 

10.27 

• GpiCharStringAt 

Purpose: 

Draws a line of text at a specified starting position. 
Prototype: 

LONG APIENTRY GpiCharStringAt 
(HPS hps, 

PPOINTL pptlStart, 

LONG cchString, 

PCH pchString); 


Figure: 

3.28 
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• GpiCreateLogFont 

Purpose: 

Creates a logical definition of a font. 

Prototype: 

BOOL APIENTRY GpiCreateLogFont 
(HPS hps, 

PSTR8 pchName, 

LONG lcid, 

PFATTRS pfat); 

Figure: 

3.26 

® GpiDeleteBitmap 

Purpose: 

Frees a bitmap. 

Prototype: 

BOOL APIENTRY GpiDeleteBitmap 
(HBITMAP hbm) ; 

Figure: 

10.23 

• GpiErase 

Purpose: 

Erases the display device associated with the specified 
presentation space using the default system background 
color (CLR BACKGROUND). 

Prototype: 

BOOL APIENTRY GpiErase 
(HPS hps); 
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Figure: 

10.12 

• GpiLine 

Purpose: 

Draws a straight line from the current graphics position to 
the specified endpoint, and resets the current graphics posi¬ 
tion to this endpoint. 

Prototype: 

LONG APIENTRY GpiLine 
(HPS hps, 

PPOINTL pptl); 


Figure: 

11.23 

• GpiLoadBitmap 

Purpose: 

Loads a bitmap from a resource segment into memory. 
Prototype: 

HBITMAP APXENTRY GpiLoadBitmap 
(HPS hps, 

USHORT hModule, 

USHORT idBitmap, 

LONG 1Width, 

LONG iHeight); 


Figure: 

10.21 

GpiLoadFonts 

Purpose: 

Loads one or more fonts from a font file. 
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Prototype: 

BOOL APIENTRY GpiLoadFonts 
(HAB hab, 

PSZ pszFilename); 


Figure: 

3.18 

GpiMove 

Purpose: 

Sets the current graphics position. 
Prototype: 

BOOL APIENTRY GpiMove 
(HPS hps, 

PPOINTL pptl); 


Figure: 

11.22 

GpiQueryFonts 

Purpose: 

Returns information on one or more of the fonts that are cur¬ 
rently available. 

Prototype: 

LONG APIENTRY GpiQueryFonts 
(HPS hps, 

ULONG flOptions, 

PSZ pszFacename, 

PLONG pcFonts, 

LONG cbMetrics 
PFONTMETRICS pfmMetrics); 


Figure: 

3.20 
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• GpiSetBackColor 

Purpose: 

Sets the background color generated by graphics functions 
such as GpiCharStringAt. 

Prototype: 

BOOL APIENTRY GpiSetBackColor 
(EPS hps, 

LONG IColor); 


Figure: 

9.9 

• GpiSetBackMix 

Purpose: 

Specifies the way the background color generated by 
graphics functions (such as GpiCharStringAt) is combined 
with the existing color within the presentation space. 

Prototype: 

BOOL APIENTRY GpiSetBackMix 
(HPS hps, 

LONG IMixMode); 


Figure: 

9.8 

• GpiSetCharSet 

Purpose: 

Sets the current character set used for displaying textual data 
within the specified presentation space. 
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Prototype: 

BOOL APIENTRY GpiSetCharSet 
(HPS hps, 

LONG Icid); 


Figure: 

3.27 

GpiSetColor 

Purpose: 

Sets the foreground color used by Gpi functions such as Gpi- 
CharStringAt. 

Prototype: 

BOOL APIENTRY GpiSetColor 
(HPS hps, 

LONG IColor); 


Figure: 

3.29 


WinAlarm 

Purpose: 

Sounds the computer speaker. 


Prototype: 

BOOL APIENTRY WinAlarm 
(HWND hwndDesktop, 
USHORT rgfType); 


Figure: 

6.9 
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• WinAllocMem 

Purpose: 

Allocates a block of memory from a Presentation Manager 
heap. 

Prototype: 

NPBYTE APIENTRY WinAllocMem 
(HHEAP hHeap, 

USHORT cb); 


Figure: 

3.7 

• WinBeginPaint 

Purpose: 

Obtains a handle to a presentation space that is associated 
with the specified window. 

Prototype: 

EPS APIENTRY WinBeginPaint 
(HWND hwnd, 

EPS bps, 

PRECTL prclPaint); 


Figure: 

2.20 

• WinCloseClipbrd 

Purpose: 

Closes the clipboard, previously opened through WinOpem- 
Clipbrd. 
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Prototype: 

BOOL APIENTRY WinCloseClipbrd 
(HAB hab); 


Figure: 

9.4 

WinCreateCursor 

Purpose: 

Creates a cursor within the specified window. 

Prototype: 

BOOL APIENTRY WinCreateCursor 
(HWND hwnd, 

SHORT x r 
SHORT y, 

SHORT cx, 

SHORT cy, 

USHORT fs, 

PRECTL prclClip); 


Figure: 

5.3 

WinCreateHeap 

Purpose: 

Creates and initializes a heap for dynamically allocating 
blocks of memory. 

Prototype: 

HHEAP APIENTRY WinCreateHeap 
(USHORT selHeapBase, 

USHORT cbHeap, 

USHORT cbGrow, 

USHORT cbMinDed, 



642 Programmer's Guide to the OS/2 Presentation Manager 




USHORT cbMaxDed, 
USHORT fOptions); 


Figure: 

Figure 3.4 

• WinCreateMsgQueue 

Purpose: 

Establishes a message queue that receives messages sent to 
all windows created by the current thread. 

Prototype: 

HMQ APIENTRY WinCreateMsgQueue 
(HAB hab, 

SHORT cmsg); 


Figure: 

2.3 

• WinCreateStdWindow 

Purpose: 

Creates a standard window. 

Prototype: 

HWND APIENTRY WinCreateStdWindow 
(HWND hwndP arent, 

ULONG flStyle, 

PVOID pCtlData, 

PSZ pszClientClass, 

PSZ pszTitle, 

ULONG styleClient, 

HMODULE hmod, 

USHORT idResources, 

PHWND phwndClient); 
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Figure: 

2.5 

WinCreateWindow 

Purpose: 

Creates a new window. 

Prototype: 

HWND APIENTRY WinCreateWindow 
(HWND hwndParent, 

PSZ pszClass, 

PSZ pszName, 

ULONG flStyle, 

SHORT x, 

SHORT y, 

SHORT cx , 

SHORT cy, 

HWND hwndOwner, 

HWND hwndlnsertBehind, 
USHORT id, 

PVOID pCtlData, 

PVOID pPresParams); 


Figure: 

12.12 

• WinDefDlgProc 

Purpose: 

Provides default processing for a message sent to a dialog 
procedure. 

Prototype: 

ULONG APIENTRY WinDefDlgProc 
(HWND hwndDlg, 

USHORT msgid, 
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MPARAM mpl, 
MPARAM mp2); 


Figure: 

8.10 

• WinDefWindowProc 

Purpose: 

Passes a message to the system for default processing. 
Prototype: 

MRESULT APIENTRY WinDefWindowProc 
(HWND hwnd, 

USHORT msg, 

MPARAM mpl, 

MP ARAM mp2) ; 


Figure: 

2.17 

• WinDestroyCursor 

Purpose: 

Destroys the cursor associated with the specified window. 
Prototype: 

BOOL APIENTRY WinDestroyCursor 
(HWND hwnd); 


Figure: 

5.6 

® WinDestroyHeap 

Purpose: 

Destroys a heap previously created by WinCreateHeap. 




Prototype: 

HHEAP APIENTRY WinDestroyHeap 
(HHRAP hHeap); 

Figure: 

3.5 

• WinDestroyMsgQueue 

Purpose: 

Destroys the specified message queue. 

Prototype: 

BOOL APIENTRY WinDestroyMsgQueue 
(HMQ hmq); 

Figure: 

2.14 

• WinDestroyPointer 

Purpose: 

Destroys an icon or pointer. 

Prototype: 

BOOL APIENTRY WinDestroyPointer 
(HPOINTER hptr); 

Figure: 

10.10 

• WinDestroyWindow 

Purpose: 

Destroys the specified window and all its descendant 
windows. 
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Prototype: 

BOOL APIENTRY WinDestroyWindow 
(HWND hwnd); 


Figure: 

2.13 

• WinDismissDIg 

Purpose: 

Removes the current dialog box and causes the function 
WinDlgBox to return control. 

Prototype: 

BOOL APIENTRY WinDismissDIg 
(HWND hwndDlg, 

USHORT usResult); 


Figure: 

8.11 

• WinDispatchMsg 

Purpose: 

Causes the system to call a window procedure. 
Prototype: 

ULONG APIENTRY WinDispatchMsg 
(HAB hab, 

PQMSG pqmsg); 


Figure: 

2.9 

® WinDlgBox 

Purpose: 

Loads, displays, and processes a dialog box. 



Selected Presentation Manager Functions 


647 


Prototype: 

USHORT APIENTRY WinDlgBox 
(HWND hwndParent , 

HWND hwndOwner , 

PFNWP pfnDlgProc, 
HMODULR hmod, 

USHORT idDlg, 

PVOID pCreateParams); 


Figure: 

8.9 

WinDrawBitmap 

Purpose: 

Draws a bitmap within the specified presentation space. 

Prototype: 

BOOL APIENTRY WinDrawBitmap 
(HPS hpsDst, 

KBIT MAP hbrn, 

PRECTL pwrcSrc, 

PPOINTL pptlDst, 

LONG clrFore, 

LONG clrBack, 

USHORT fs); 


Figure: 

10.22 

• WinDrawPointer 

Purpose: 

Draws an icon. 

Prototype: 

BOOL APIENTRY WinDrawPointer 
(HPS hps, 
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SHORT x, 

SHORT y, 

HPOINTER hptr, 

USHORT fs); 

Figure: 

10.9 

• WinDrawText 

Purpose: 

Prints a text string within a specified rectangle, using the cur¬ 
rent font. 6 

Prototype: 

SHORT APIENTRY WinDrawText 
(HPS hps, 

SHORT cchText, 

PCH pchText, 

PRECTL prcl, 

LONG clrFore, 

LONG clrBack, 

USHORT rgfCmd); 

Figure: 

2.24 

• WinEmptyClipbrd 

Purpose: 

Removes all data blocks from the clipboard, freeing the as¬ 
sociated data handles. 

Prototype: 

BOOL APIENTRY WinEmptyClipbrd 
(HAB hab) ; 




Figure: 

9.6 

• WinEnableWindow 

Purpose: 

Enables or disables the specified window. 

Prototype: 

BOOL APIENTRY WinEnableWindow 
(HWND hwnd, 

BOOL fEnable); 

Figure: 

4.10 

• WinEndPaint 

Purpose: 

Signals the system that the updating of the window (which 
occurs typically in response to a WM_PAINT message) is 
complete. 

Prototype: 

bool APIENTRY WinEndPaint 
(HPS hps); 

Figure: 

2.21 

• WinFillRect 

Purpose: 

Draws a rectangle filled with a specified color. 

Prototype: 

BOOL APIENTRY WinFillRect 
(HPS hps, 
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PRECTL perl, 
LONG IColor); 


Figure: 

2.23 

• WinFreeMem 

Purpose: 

Frees a memory block from a heap managed by the Presenta¬ 
tion Manager. 

Prototype: 

NPBYTE APIENTRY WinFreeMem 
(HHEAP hHeap, 

NPBYTE npMem, 

USHORT cbMem); 


Figure: 

3.10 

• WinGetKeyState 

Purpose: 

Determines whether a virtual key or mouse button is cur¬ 
rently pressed or released; also returns the toggle status of 
a key. 

Prototype: 

SHORT APIENTRY WinGetKeyState 
(HWND hwndDesktop, 

SHORT vkey) ; 


Figure: 

11.16 
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WinGetLastError 

Purpose: 

Returns the system error code set by the last Presentation 
Manager function that failed, and resets the system error 
code to 0. 

Prototype: 

ERRORID APIENTRY WinGetLastError 
(HAB hab); 


Figure: 

3.11 

• WinGetMsg 

Purpose: 

Extracts the next message from the message queue belong¬ 
ing to the current thread. 

Prototype: 

BOOL APIENTRY WinGetMsg 
(HAB hab, 

PQMSG pqmsg, 

HWND hwndFilter, 

USHORT msgFilterFirst, 

USHORT msgFilterLast); 


Figure: 

2.8 

• WinGetPS 

Purpose: 

Obtains a cache presentation space. 
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Manager 

Prototype: 

HPS APIENTRY WinGetPS 
(HWND hwnd); 

Figure: 

3.19 

• Winlnitialize 

Purpose: 

Initializes the Presentation Manager system for use by the 
current program. 

Prototype: 

HAB APIENTRY Winlnitialize 
(USHORT fOptions)/ 

Figure: 

2.2 

• WinlnvalidateRect 

Purpose: 

Adds a rectangular area to a window 7 s update region. 
Prototype: 

BOOL APIENTRY WinlnvalidateRect 
(HWND hwnd, 

PRECTL prcl, 

BOOL fIncludeChildren); 


Figure: 

5.8 
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WinLoadPointer 

Purpose: 

Loads an icon or mouse pointer into memory from a 
resource segment contained in a disk file. 

Prototype: 

HPOINTER APIENTRY WinLoadPointer 
(HWND hwndDesktop, 

HMODULE hmod, 

USHORT idres); 


Figure: 

10.8 

• WinLoadString 

Purpose: 

Loads a string from a string table resource into a program 
buffer. 

Prototype: 

SHORT APIENTRY WinLoadString 
(HAB hab , 

HMODULE hmod, 

USHORT id, 

SHORT cchMax, 

PSZ pchBuffer); 


Figure: 

10.25 

• WinLockHeap 

Purpose: 

Supplies the far address of the base of the segment contain¬ 
ing the specified heap. 
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Prototype: 

PVOID APIENTRY WinLockHeap 
(HHEAP hHeap); 


Figure: 

3.6 

* WinMapWindowPoints 

Purpose: 

M a p s the coordinates of one or more points from the coor- 
dinate space relative to one window into the coordinate 
space relative to another window. 

Prototype: 

BOOL APIENTRY WinMapWindowPoints 
(HWND hwndFrom, 

HWND hwndTo, 

PPOINTL pptl, 

SHORT cwpt); 


Figure: 

11.4 

• WinMessageBox 

Purpose: 

Displays a message box window. 
Prototype: 

USHORT APIENTRY WinMessageBox 
(HWND hwndParent , 

HWND hwndOwner, 

PSZ pszText, 

PSZ pszCaption, 

USHORT idWindow, 

USHORT flStyle); 
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Figure: 

3.14 

• WinOpenClipbrd 

Purpose: 

Opens the clipboard for the current thread, to provide this 
thread exclusive access to the clipboard. 

Prototype: 

BOOL APIENTRY WinOpenClipbrd 
(HAS hab); 


Figure: 

9.2 

• WinPostMsg 

Purpose: 

Posts a message to the message queue belonging to the 
specified window. 

Prototype: 

BOOL APIENTRY WinPostMsg 
(HWND hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2); 


Figure: 

12.11 

• WinQueryClipbrdData 

Purpose: 

Returns a handle to the block of data in the clipboard that 
has the requested format. 
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Prototype: 

ULONG APIENTRY WinQueryClipbrdData 
(HAB hab, 

USHORT fmt); 


Figure: 

9.5 

• WinQueryFocus 

Purpose: 

Obtains the handle of the focus window. 
Prototype: 

HWND APIENTRY WinQueryFocus 
(HWND hwndDesktop, 

BOOL fLock); 


Figure: 

5.10 

• WinQueryMsgPos 

Purpose: 

Obtains the position of the mouse pointer at the time the last 
message extracted from the message queue was posted. The 
position is given in screen coordinates. 

Prototype: 

BOOL APIENTRY WinQueryMsgPos 
(HAB hab, 

PPOINTL pptl); 


Figure: 

11.3 
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WinQueryPointerPos 

Purpose: 

Obtains the current position of the mouse pointer in screen 
coordinates. 

Prototype: 

BOOL APIENTRY WinQueryPointerPos 
(HWND hwndDesktop, 

PPOINTL pptl); 


Figure: 

11.2 

WinQuerySysPointer 

Purpose: 

Returns the handle to the requested system pointer or icon. 
Prototype: 

HPOINTER APIENTRY WinQuerySysPointer 
(HWND hwndDesktop, 

SHORT iptr, 

BOOL fLoad); 


Figure: 

11.7 

WinQuerySys Value 

Purpose: 

Returns the specified system value. 
Prototype: 

LONG APIENTRY WinQuerySysValue 
(HWND hwndDesktop, 

SHORT iSysValue); 
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Figure: 

11.1 

• WinQuery Window 

Purpose: 

Returns the handle of the window that has the selected 
relationship to a specified window. 

Prototype: 

HWND APIENTRY WinQueryWindow 
(HWND hwnd, 

SHORT cmd, 

BOOL fLock); 


Figure: 

4.6 

• WinQuery WindowRect 

Purpose: 

Returns the coordinates of the specified window. 
Prototype: 

BOOL APIENTRY WinQueryWindowRect 
(HWND hwnd, 

PRECTL prclDest); 


Figure: 

2.22 

• WinQuery WindowText 

Purpose: 

Copies the text associated with a window into a program 
buffer. 
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Prototype: 

SHORT APIENTRY WinQueryWindowText 
(HWND hwnd, 

SHORT cchBufferMax, 

PSZ pszBuffer); 


Figure: 

8.16 

WinRegisterClass 

Purpose: 

Registers a window class. 

Prototype: 

BOOL APIENTRY WinRegisterClass 
(HAB hah, 

PSZ pszClassName, 

PFNWP pfnWndProc, 

ULONG flStyle, 

USHORT cbWindowData); 


Figure: 

2.4 

WinReleasePS 

Purpose: 

Releases the presentation space obtained through WinGetPS. 
Prototype: 

BOOL APIENTRY WinReleasePS 
(HPS hps); 


Figure: 

3.22 
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• WinScrollWindow 

Purpose: 

Scrolls the contents of a window a specified horizontal and 
vertical distance. 

Prototype: 

SHORT APIENTRY WinScrollWindow 
(HWND hwnd, 

SHORT dx, 

SHORT dy, 

PRECTL prclScroll, 

PRECTL preclClip, 

HRGN hrgnUpdate, 

PRECTL prclUpdate, 

USHORT rgfsw); 


Figure: 

4.14 

* WinSendDlgltemMsg 

Purpose: 

Sends a message to a child control window within a dialog 
box; the target control window is specified by its identifier 
and the parent window handle (rather than by its own win¬ 
dow handle). 

Prototype: 

MRESULT APIENTRY WinSendDlgltemMsg 
(HWND hwndDlg, 

USHORT idltem, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2) ; 
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Figure: 

8.25 

• WinSendMsg 

Purpose: 

Sends a message to the specified window. 
Prototype: 

MRESULT APIENTRY WinSendMsg 
(HWND hwnd, 

USHORT msg, 

MPARAM mpl, 

MPARAM mp2); 


Figure: 

4.8 

• WinSetClipbrdData 

Purpose: 

Places a block of data into the clipboard. 
Prototype: 

BOOL APIENTRY WinSetClipbrdData 
(HAB hab, 

ULONG ulD&ta, 

USHORT fmt, 

USHORT rgfFmtlnfo); 


Figure: 

9.3 

• WinSetFocus 

Purpose: 

Assigns the focus to the specified window. 
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Prototype: 

BOOL APIENTRY WinSetFocus 
(HWND hwndDesktop, 

HWNB hwndSetFocus); 


Figure: 

4.3 

• WinSetPointer 

Purpose: 

Sets the mouse pointer that is displayed by the system. 
Prototype: 

BOOL APIENTRY WinSetPointer 
(HWND hwndDesktop, 

HPOINTER hptrNew); 


Figure: 

11.6 

• WinSetPointerPos 

Purpose: 

Sets the position of the mouse pointer. 
Prototype: 

BOOL APIENTRY WinSetPointerPos 
(HWND hwndDesktop, 

SHORT x, 

SHORT y); 


Figure: 

11.11 
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WinS etWindo wText 

Purpose: 

Sets the text associated with a window. 
Prototype: 

BOOL APIENTRY WinSetWindowText 
(HWND hwnd, 

PSZ pszText); 


Figure: 

7.18 

WinShowCursor 

Purpose: 

Makes visible or hides the cursor associated with the 
specified window. 

Prototype: 

BOOL APIENTRY WinShowCursor 
(HWND hwnd, 

BOOL fShow); 


Figure: 

5.5 

WinShowPointer 

Purpose: 

Shows or hides the mouse pointer by changing the pointer 
hide level. 

Prototype: 

BOOL APIENTRY WinShowPointer 
(HWND hwndDesktop, 

BOOL fShow); 
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Figure: 

11.10 

• WinTerminate 

Purpose: 

Signals the Presentation Manager that the calling thread has 
completed using the services of the Presentation Manager, 
and releases all Presentation Manager resources held by this 
thread. 

Prototype: 

BOOL APIENTRY WinTerminate 
(HAB hab); 


Figure: 

2.15 

• WinUpdateWindow 

Purpose: 

Causes the system to send a WMJPAINT message to the 
specified window by directly calling the window procedure. 

Prototype: 

BOOL APIENTRY WinUpdateWindow 
(HWND hwnd); 


Figure: 

4.16 

• WinUpper 

Purpose: 

Converts the characters in a string to uppercase. 
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Prototype: 

SHORT APIENTRY WinUpper 
(HAS hab, 

USHORT idcp, 

USHORT idee, 

PSZ psz) ; 


Figure: 

7.20 

• WinWindowFromID 

Pw*pose: 

Returns the handle belonging to a child window. 
Prototype: 

HWND APIENTRY WinWindowFromID 
(HWND hwndParent , 

USHORT id); 


Figure: 

4.5 
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his appendix provides an alphabetical summary of the 
predefined Presentation Manager messages that have been 
described in this book. The synopsis of each message gives 
a brief statement of the purpose of the message and a ref¬ 
erence to the figure in the book that fully describes the message and the 
parameters that accompany it. Note that these messages fall into one of 
two general categories. The first category consists of messages that are 
typically sent to a client or dialog window procedure to notify it of user 
input or other significant events. The second category comprises mes¬ 
sages that are normally sent by a window procedure to windows man¬ 
aged by the system, to control the behavior of these windows or to 
obtain services from the system. The messages in the second category 
effectively extend the Presentation Manager API accessed through sys¬ 
tem function calls. 

The messages summarized here are also listed in the inside covers of 
the book, where each message is categorized according to the type of 
information it provides or the service it performs. Note that these func¬ 
tions form a subset of the full collection of predefined Presentation 
Manager messages; see the technical documentation cited in the Bibli 
ography for information on messages not discussed in this book. See 
also the section on Using Messages in Chapter 12 for a description of 
programmer-defined messages. 

• EM_SETTEXTLIMIT 

Purpose: 

Sent to an edit control of a dialog box to set the maximum 
number of characters that can be entered into the control. 

Figure: 

8.24 

• LMJDELETEALL 

Purpose: 

Sent to a list box control window to delete all items in the 
list box. 
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Figure: 

8.31 

• LMJNSERTITEM 

Purpose: 

Sent to a list box control window to cause it to add an item to 
the list. 

Figure: 

8.32 

• LM_QUERYSELECTION 

Purpose: 

Sent to a list box control window to obtain the index of the 
currently selected item. 

Figure: 

8.28 

• LM_QUERYITEMTEXT 

Purpose: 

Sent to a list box control window to obtain the text for a 
specific item within the list box. 

Figure: 

8.29 

• MM_SETITEMATTR 

Purpose: 

Sent to a menu window to set the attributes of a menu item. 


Figure: 

7.9 
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• MM_SETITEMTEXT 

Purpose: 

Sent to a menu control window to specify the text displayed 
for a given menu item. 

Figure: 

7.10 

• SBM_SETPOS 

Purpose: 

Sent to a horizontal or vertical scroll bar window to cause it 
to set the position of the scroll bar slider. 

Figure: 

4.17 

• SBM_SETSCROLLBAR 

Purpose: 

Sent to a horizontal or vertical scroll bar window to cause it 
to set the range and position of the scroll bar slider. 

Figure: 

4.9 

• WM_CHAR 

Purpose: 

Sent by the system to the focus window (or active window, if 
there is no focus window) to notify it of a keyboard event 
(that is, a key pressed or released). 


Figure: 

6.1 
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• WM_CLOSE 

Purpose: 

Sent by the system to the client window when the user 
selects the Close item from the system menu. 

Figure: 

12.10 

• WM^COMMAND 

Purpose: 

Sent by a control window to its owner to report a significant 
event. ° 

Figure: 

7.11 

• WM_CONTROL 

Purpose: 

Sent by a control window to its owner to report a significant 
event. 

Figure: 

8.18 

• WM_CREATE 

Purpose: 

Sent by the system to a window when it is first created. It al- 
lows the window procedure to perform initializations. 


Figure: 

3.16 
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• WM_DESTROY 

Purpose: 

Sent by the system to a window when it is about to be 
destroyed. 

Figure: 

10.11 

. WM_ERASEBACKGROUND 

Purpose: 

Sent to the client window so that the client window proce¬ 
dure can either erase the window itself, or have the system 
erase the window using the default background color 
(CLR_BACKGROUND). 

Figure: 

11.15 

• WM_HSCROLL 

Purpose: 

Sent by a horizontal scroll bar window to its owner to report 
relevant scroll bar events. 

Figure: 

4.12 

• WMJNITDLG 

Purpose: 

Sent by the system to a dialog window when it is first 
created, before it becomes visible. 


Figure: 

8.19 
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• WM_INITMENU 

Pmpose: 

Sent by the system to the client window when a menu item 
is about to become active. 

Figure: 

7.7 

• WM_MOUSEMOVE 

Purpose: 

Sent by the system to the window beneath the mouse pointer 
(or to the mouse capture window, if any) each time the posi¬ 
tion of the mouse pointer changes. 

Figure: 

11.5 

• WM_PAINT 

Purpose: 

Sent by the system to a window whenever the entire win¬ 
dow, or any portion of it, needs redrawing. 

Figure: 

2.19 

• WM„OtJIT 

Purpose: 

Posted to the message queue to terminate the application. 

Figure: 

2.10 
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• WM_SETFOCUS 

Purpose: 

Sent by the system to a window whenever it is about to 
receive or lose the input focus. 

Figure: 

5.1 

• WM_SIZE 

Purpose: 

Sent by the system to a window whenever its size changes. 


Figure: 

3.23 

• WM_V SCROLL 

Purpose: 

Sent by a vertical scroll bar window to its owner to report 
relevant scroll bar events. 


Figure: 

4.18 
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. A 

accelerators (keyboard), 43-44, 263, 
301-335 

creating, 301-310 
managing, 311-322 
anchor block handle, 28,30-32 
API (application program interface) 
general, 14-15,16-18 
Presentation Manager, 24-25 
automatic data segment, 92, 94 

. B 

Backspace key, 252-259 
bitmaps, 486-487, 512-526 

a C 

fc (compiler flag), 72 
cache presentation space. See 
presentation space 
character code (keyboard), 231 
CHARMSG (macro), 228-229 
child window, 38,47-49 
class. See window class 
Clear command, 479,483 
click (mouse button), 579-580 
client window, 36,46-47 
clipboard, 461-489 

accessing data in, 473-478 
adding data to, 461-473 
advanced features of, 485-489 
closing, 472-473, 478 


formats for, 486-487 
interface to, 479-485 
opening, 466-468, 474 
clipboard viewer window, 487-488 
colors (for windows), 69-70, 

509-510 

COMMANDMSG (OS/2 macro), 

320 

compatibility box, 4, 6 
control flags (keyboard), 235 
Control Panel (of Presentation 
Manager), 20-21 
control windows, 38-49 
Copy command, 479, 483 
Courier (font), 114-117 
Ctrl-click (mouse), 581 
Ctrl-drag (mouse), 581 
current graphics position, 574-576 
cursor, 199-224 
creating, 200-208 
maintaining, 208-213 
moving, 213-224 
Cut command, 479, 483 

. D 

default push button, 346 

Del key (Delete), 256,262 

descriptor (segment), 7-11 

descriptor table, 7-11 

desktop window, 41, 356 

device context, 65, 67 

dialog box editor, 338-343, 510-511 
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dialog boxes, 337-457 
creating, 337-356 
managing, 356-395 
dialog frame, 346 
dialog procedure, 354,356-359 
Dos functions, 16-18 
DosAllocSeg, 462-464, 589, 631 
DosCreateThread, 584-585, 
588-589, 631-632 
DosExit, 590, 592,632 
DosGetResource, 530-531, 632 
DosGetSeg, 476-478, 632-633 
DosSemClear, 595, 597, 633 
DosSemSet, 595-596, 633 
DosSemWait, 595, 597-600, 605, 
633-634 

DosSizeSeg, 532-533, 634 
double-click (mouse button), 
579-581 

drag (mouse), 579-581 
dynamic-link libraries, 11-16 
dynamic linking, 11-16 

® E 

EM_SETTEXTLIMIT, 376-380, 667 

Enter key, 249-252 

errors 

handling, 101-113 
return codes for, 104 
exit, 333 

EXPORTS (linker definition file 
command), 74 

«F 

features of Presentation Manager, 
18-25 


Filing System (of Presentation 
Manager), 21 
Find command, 362-371 
Find Next command, 371-372 
focus window, 150-151,212-213, 
228 

fonts (managing), 114-122 
frame window, 38-49 

• G 

/G2 (compiler flag), 72 
/Gs (compiler flag), 73 
/GW (compiler flag), 73 
global descriptor table, 10 
Go to Line command, 372-375 
GpiCharStringAt, 128,130-133, 
267, 634 

GpiCreateLogFont, 126-128, 635 
GpiDeleteBitmap, 519,523-524, 

635 

GpiErase, 509-510, 635-636 
GpiLine, 574, 576-577, 636 
GpiLoadBitmap, 519-521, 636 
GpiLoadFonts, 114,117, 636-637 
GpiMove, 574-575,577, 637 
GpiQueryFonts, 115-120, 637 
GpiSetBackColor, 267,480,482, 638 
GpiSetBackMix, 267, 480-481, 638 
GpiSetCharSet, 126,129, 638-639 
GpiSetColor, 128,131,639 

.H 

handles, 74r-75 

header files (OS/2), 27-28, 81-82 
heap, managing, 83-101 
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HEAPSIZE (linker definition file 
command), 74, 94 
hot spot (mouse pointer), 512,541 

. I 

icon editor, 498-500,512-513,519 
icons, 41,45,491-512 
designing, 498-500 
displaying, 502-512 
installing, 500-502 
identifier. See window identifier 
import library, 11-12 
include files. See header files 
initializing (Presentation Manager), 
28,30-33 

Ins key (Insert), 262-264 
insert mode, 333-334 
insertion point, 199 
interprocess communication, 6-7, 
594-609. See also multitasking, 
semaphores, threads 
invalid areas (of windows), 62-65, 
70,168,171,180 

e K 

kernel applications, 22-23 
keyboard, 227-298 
keyboard accelerators. See 
accelerators 

® L 

linker definition file, 73-74 
linking, 11-16,73 

LMJDELETEALL, 391,394,667-668 
LMJNSERTITEM, 391, 395,668 


LM_QUERYITEMTEXT, 389-390, 

668 

LM_QUERYSELECTION, 389, 668 
local descriptor table, 10 

• M 

macros (provided by OS/2), 84-89 
MAKE (utility), 72 
menu command, 484 
menu mnemonic, 484 
menus, 301-335 
creating, 301-310 
managing, 311-322 
message-based architecture, 56-57 
message queue, 33-34 
messages 

for interprocess communication, 
606-609 

getting and dispatching, 49-57 
processing, 58-60 
sending, 158-160,215 
metafile, 486-487 
MM_SETITEMATTR (message), 
315-317, 668 

MM_SETITEMTEXT (message), 
317-318, 669 

module definition file. See linker 
definition file 
mouse, 535-581 

creating an interface for, 578-581 
finding pointer location, 535-546 
reading the buttons, 563-578 
setting pointer shape, 547-563 
MS-DOS applications, 22 
multitasking, 6-7, 583-609 
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.N 

NAME (linker definition file 
command), 73 
New command, 322-330 

® O 

object windows, 606,608 
Open command, 380-395 
overwrite mode, 333-334 
owner (of a window), 109,112 

• P 

parent window, 38,47-49 
Pascal conventions, 31-33 
Paste command, 479,483 
point (mouse), 579 
pointer (mouse), 512 
presentation space, 65-69, 115,118 
privilege levels, 10-11 
Program Starter, 20 
programmer-defined resources, 
529-533 

proportionally spaced characters, 
114-115 

protected-mode screen groups, 4-6 
protection fault, 10 
PROTMODE (linker definition file 
command), 74 

• 0 

queue. See message queue, system 
queue 

® R, 

real mode screen group, 4, 6 


relocation record, 11-12 
repeat count (keyboard), 232 
resource compiler, 302-304 
resource script, 302-309 
resources (OS/2), 301-302,491-533. 
See also accelerators, bitmaps, 
dialog boxes, icons, menus, 
programmer-defined 
resources, strings 
Return key. See Enter key 

. S 

Save As command, 375-380 
Save command, 330-333 
scan code (keyboard), 231 
screen groups, 3-6 
scroll bars, 147-197 
selection (of data) 
described, 479 
marking, 480-483 
selector (segment), 7-11 
semaphores, 594-605 
session manager, 5-6 
sessions, 3-6 

SBM_SETPOS (message), 173-174, 
669 

SBM_SETSCROLLBAR (message), 
158, 161, 669 

Shift-click (mouse), 580-581 
Shift-drag (mouse), 580 
stack (for new threads), 588-589 
STACKSIZE (linker definition file 
command), 74, 94 
standard window, 38-49 
strings (stored as resources), 

526-529 

styles. See window styles 
system queue, 227-228 
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. T 

tab characters, 268 
Tab key, 248-249 
Task Manager, 19-20 
threads (program), 584-609 
communicating between, 

59T-609 

starting, 585-593 
see also interprocess 
communication, multitasking, 
semaphores 

title (window), 39,46-47 

@ U 

user interface shell (of Presentation 
Manager), 18-21 

. V 

Vio functions, 16-17, 24-25 
virtual-key codes, 180,214,231-234 
virtual keys, processing, 259-264 
virtual memory, 7-11 

. W 

/W2 (compiler flag), 72 
WinAlarm, 246-247,256,538-539, 
599, 639 

WinAllocMem, 97,99,640 
WinBeginPaint, 65-69,180,640 
WinCloseClipbrd, 472M73,478, 
640-641 

WinCreateCursor, 200-207, 
211-212,217-218, 224,641 
WinCreateHeap, 92-96,641-642 
WinCreateMsgQueue, 33-34, 642 


WinCreateStdWindow, 38-49,147, 
309, 642-643 

WinCreateWindow, 606, 608-609, 

643 

WinDefDlgProc, 357-358, 643-644 
WinDefWindowProc, 59, 62, 644 
WinDestroyCursor, 207-208, 644 
WinDestroyHeap, 96-97, 601, 

644- 645 

WinDestroyMsgQueue, 58-59, 645 
WinDestroyPointer, 502,505-507, 
512, 551,560,573, 645 
WinDestroyWindow, 57-58, 

645— 646 

WinDismissDlg, 356-357,359, 646 
WinDispatchMsg, 49,51-57,545, 
583, 646 

WinDlgBox, 354-357,360, 646-647 
window class, 34-39,46-47 
window identifiers, 153,155-156 
window procedure, 34,37,54-57 
window styles, 34-38,41-46 
windows, creating, 38-49 
WinDrawBitmap, 519,522-526, 647 
WinDrawPointer, 502,504, 507, 

647- 648 

WinDrawText, 69-71, 508-509, 648 
WinEmptyClipbrd, 475-476, 

648- 649 

WinEnableWindow, 42,159,162, 
369, 649 

WinEndPaint, 65, 67-68,649 
WinFillRect, 69-70,649-650 
WinFreeMem, 101-103, 650 
WinGetKeyState, 564-565, 650 
WinGetLastError, 102,105, 651 
WinGetMsg, 49-53, 57,583, 603, 
651 
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WinGetPS, 115,118, 266,574, 
651-652 

Winlnitialize, 28, 30-33, 652 
WinlnvalidateRect, 209-211, 652 
WinLoadPointer, 502-503,505-506, 
512,550-551,573,653 
WinLoadString, 528-529, 653 
WinLockHeap, 96, 98, 653-654 
WinMapWindowPoints, 537-538, 
544,554, 654 

WinMessageBox, 107,110-112, 
323—324, 600, 654—655 
WinOpenClipbrd, 466-468,474, 655 
WinPostMsg, 159, 603-604,655 
WinQueryClipbrdData, 474-475, 
655-656 

WinQueiyFocus, 212-213, 656 
WinQueryMsgPos, 537,541, 543, 
545, 656 

WinQueiyPointerPos, 537,542, 657 
WinQuerySysPointer, 502, 

547-549, 560, 657 
WinQueiySys Value, 535-541, 
563-564, 567, 657-658 
WinQueryWindow, 153-155,658 
WinQueryWindowRect, 68, 

524-525, 658 

WinQueryWindowText, 367-369, 
658-659 

WinRegisterClass, 34-38, 659 
WinReleasePS, 122, 266,575,659 
WinScrollWindow, 168-173, 223 , 

660 

WinSendDlgltemMsg, 379,381, 
660-661 

WinSendMsg, 158-160,179,605, 

661 

WinSetCapture, 545 


WinSetClipbrdData, 468-471,661 
WinSetFocus, 150-151, 661-662 
WinSetPointer, 512,547-548, 
550-551,560-561,574,662 
WinSetPointerPos, 554, 662 
WinSetSys Value, 567 
WinSetWindowText, 327-328, 663 
WinShowCursor, 207,223-224, 663 
WinShowPointer, 552-553, 663-664 
WinTerminate, 58,60,664 
WinUpdateWindow, 171-173, 664 
WinUpper, 328,330,664-665 
WinWindowFromID, 153,310, 665 
WM BUTTON1 DOWN (mouse 
message), 566,574 
WM_CHAR (message), 179-180, 
227-236,669 

WM_CLOSE (message), 601-603, 

670 

WM_COMMAND (message), 
318-320,382, 388,670 
WM_CONTROL (message), 

368-369,388-391, 670 
WMCREATE (message), 114-115, 
151-155,200, 670 

WM__DESTROY (message), 506, 671 
WM_ERASEBACKGROUND, 
561-563,578, 671 
WM_HELP (message), 320-322 
WMHSCROLL (message), 

163-174, 671 

WM INITDLG (message), 357, 
370-371,391-395, 671 
WM_INITMENU (message), 

311-318, 672 

WM_MOUSEMOVE (message), 
545-546,551-552,574,672 



WM_PAINT (message), 42,49,52, 
59,61-65,124-133,200, 672 
WM_QUIT (message), 53-54,57, 
602-603, 672 

WM_SETFOCUS (message), 
200-202, 368, 673 
WM_SIZE (message), 123-124, 
155-162, 200, 673 
WMJVSCROLL (message), 
174-179, 673 


. Z 

/Zp (compiler flag), 72 
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The SYBEX Library 


DOS 


The ABC's ©f DOS 4 
Alan R. Miller 
250pp. Ref. 583-2 

This step-by-step introduction to using 
DOS 4 is written especially for beginners. 
Filled with simple examples, The ABC’s of 
DOS 4 covers .the basics of hardware, 
software, disks, the system editor EDUN,’ 
DOS commands, and more. 

ABC's ®f MS-DOS 
(Second Edition) 

Alan R. Miller 
233pp. Ref. 493-3 

This handy guide to MS-DOS is all many 
PC users need to manage their computer 
files, organize floppy and hard disks, use 
EDLIN, and keep their computers orga¬ 
nized. Additional information is given 
about utilities like Sidekick, and there is a 
DOS command and program summary. 
The second edition is fully updated for 
Version 3.3. 

Mastering DOS 
(Second Edition) 

Judd Robbins 

700pp. Ref. 555-7 

“The most useful DOS book.” This seven- 
part, in-depth tutorial addresses the 
needs of users at all levels. Topics range 
from running applications, to managing 
files and directories, configuring the sys¬ 
tem, batch file programming, and tech¬ 
niques for system developers. 

MS-DOS Handbook 
(Third Edition) 

Richard Alien King 
362pp. Ref. 492-5 

This classic has been fully expanded and 


revised to include the latest features of 
MS-DOS Version 3.3. Two reference 
books in one, this title has separate sec¬ 
tions for programmer and user. Multi-DOS 
partitons, 3 1/2disk format, batch file call 
and return feature, and comprehensive 
coverage of MS-DOS commands are 
included. 

MS-DOS Power User's Guide, 
Volume I 
(Second Edition) 

Jonathan Kamin 
482pp. Ref. 473-9 

A fully revised, expanded edition of our 
best-selling guide to high-performance 
DOS techniques and utilities-with details 
on Version 3.3. Configuration, I/O, direc¬ 
tory structures, hard disks, RAM disks, 
batch file programming, the ANSI.SYS 
device driver, more. 

MS-DOS Power User's Guide, 
Volume II 

Martin Waterhouse/Jonathan Kamin 

418pp, Ref. 411-9 

A second volume of high-performance 
techniques and utilities, with expanded 
coverage of DOS 3.3, and new material 
on video modes, Token-Ring and PC Net¬ 
work support, micro-mainframe links, 
extended and expanded memory, multi¬ 
tasking systems, and more. 

DOS User's Desktop Comparison 
Judd Robbins 

969 pp. Ref. 505-0 Softcover 
459-3 Flardcover 

This comprehensive reference covers 
DOS commands, batch files, memory 
enhancements, printing, communications 
and more information on optimizing each 
user’s DOS environment. Written with 
step-by-step instructions and plenty of 
examples, this volume covers all versions 
through 3.3. 


MS-DOS Advanced 
Programming 
Michael J. Young 
490pp. Ref. 578-6 

Practical techniques for maximizing perfor¬ 
mance in MS-DOS software by making 
best use of system resources. Topics 
include functions, interrupts, devices, multi¬ 
tasking, memory residency and more, with 
examples in C and assembler. 

Essential PC-DOS 
(Second Edition) 

Myril Clement Shaw/ 

Susan Soltis Shaw 

332pp. Ref. 413-5 

An authoritative guide to PC-DOS, includ¬ 
ing version 3.2. Designed to make experts 
out of beginners, it explores everything 
from disk management to batch file 
programming. Includes an 85-page 
command summary 

The IBM PC-DOS Handbook 
(Third Edition) 

Richard Allen King 

359pp. Ref. 512-3 

A guide to the inner workings of PC-DOS 
3.2, for intermediate to advanced users 
and programmers of the IBM PC series. 
Topics include disk, screen and port con¬ 
trol, batch files, networks, compatibility, 
and more. 

OTHER OPERATING 
SYSTEMS AND 
ENVIRONMENTS 

Essential OS/2 

Judd Robbins 

367pp. Ref. 478-X 

This introduction to OS/2 for new and pro¬ 
spective users offers clear explanations of 
multitasking, details key OS/2 commands 
and functions, and updates current DOS 
users to the new OS/2 world. Details are 
also given for users to run existing DOS 
programs under OS/2. 


Programmer's Guide to OS/2 
Michael J. Young 
625pp. Ref. 464-X 

This concise introduction gives a com¬ 
plete overview of program development 
under OS/2, with careful attention to new 
tools and features. Topics include MS- 
DOS compatibility, device drivers, serv¬ 
ices, graphics, windows, the LAN 
manager, and more. 

Programmer's Guide to GEM 
Phillip Balma/WilSiam Fitter 
504pp. Ref. 297-3 

GEM programming from the ground up, 
including the Resource Construction Set, 
ICON Editor, and Virtual Device Interface. 
Build a complete graphics application 
with objects, events, menus, windows, 
alerts and dialogs. 

Understanding Hard Disk 
Management 
Jonathan Kamin 
500pp. Ref. 561-1 

Put your work, your office or your entire 
business literally at your fingertips, in a cus¬ 
tomized, automated MS-DOS work environ¬ 
ment. Topics include RAM disks, extended 
and expanded memory, and more. 

Programmer's Guide to 

Windows 

(Second Edition) 

David Durant/Geta Carlson/Paul Yao 
704pp. Ref. 496-8 

The first edition of this programmer’s 
guide was hailed as a classic. This new 
edition covers Windows 2 and Windows/ 
386 in depth. Special emphasis is given to 
over fifty new routines to the Windows 
interface, and to preparation for OS/2 
Presentation Manager compatibility. 

Graphics Programming Under 
Windows 

Brian Myers/Chris Doner 
646pp. Ref. 448-8 

Straightforward discussion, abundant 
examples, and a concise reference guide 
to graphics commands make this book a 
must for Windows programmers. Topics 



range from how Windows works to pro¬ 
gramming for business, animation, CAD, 
and desktop publishing. For Version 2. 


ASSEMBLY 

LANGUAGE 


Programming the 8086/8088 
James W. Coffron 
311pp. Ref. 120-9 

A concise introduction to assembly- 
language programming for 8086/8088- 
based systems, including the IBM PC. 
Topics include architecture, memory organi¬ 
zation, the complete instruction set, inter¬ 
rupts, I/O, and IBM PC BIOS routines. 

Programming the 80286 
C. VieiSlefond 
487pp. Ref. 277-9 

In-depth treatment of assembly-level pro¬ 
gramming for the IBM PC/AT’s 80286 
processor. Topics include system archi¬ 
tecture, memory management, address 
modes, multitasking and more; plus a 
complete reference guide to the instruc¬ 
tion set. 

Programming the 80386 

John H. Crawford/ 

Patrick P. GeSsinger 
775pp. Ref. 381-3 

A detailed tour of the 80386 for assembly- 
language programmers. Topics include 
registers, data types and instruction 
classes, memory management, protec¬ 
tion models, multitasking, interrupts, the 
numerics coprocessor, and more. 

DOS Assembly Language 
Programming 

ASan FL Miiler 

365pp. Ref. 487-9 

This book covers PC-DOS through 3.3 
and gives clear explanations of how to 
assemble, link, and debug 8086, 8088, 
80286, and 80386 programs. The 
example assembly language routines are 


valuable for students and programmers 
alike. 

Programming the 68000 

Steve Williams 

539pp. Ref. 133-0 

This tutorial introduction to assembly- 
language programming covers the com¬ 
plete 68000 architecture and instruction 
set, as well as advanced topics such as 
interrupts, I/O programming, and interfac¬ 
ing with high-level languages. 

Programming the 6809 
Rodnay Zaks/WIISsam Labiak 
362pp. Ref. 078-4 

A step-by-step course in assembly- 
language programming for 6809-based 
home computers. Covers hardware orga¬ 
nization, the instruction set, addressing, 
I/O, data structures, program develop¬ 
ment and complete sample applications. 

Programming the 6502 
Rodnay Zaks 
408pp. Ref. 135-7 

The best-selling, step-by-step course in 
assembly-language programming for the 
6502 chip used in Apple, Atari and Com¬ 
modore computers. From basic concepts 
to architecture, instruction set, address¬ 
ing, I/O, sample applications and more. 

Programming the Z80 
(Third Edition) 

Rodnay Zaks 

624pp. Ref. 069-5 

A self-teaching guide to assembly-language 
programming for the wide range of Z80- 
based microcomputers. Includes the 
Z80 architecture and instruction set, 
addressing, I/O techniques and devices, 
data structures and sample programs. 

Z 80 Applications 

James W. Coffron 

295pp. Ref. 094-6 

A handbook for assembly-language 
programmers on the principles of Z80 
hardware operations. Topics include 
using ROM, static and dynamic RAM, I/O, 
interrupts, serial communication and 
several specific LSI peripheral devices. 



LANGUAGES 

Mastering Turbo Pascal 5 
Douglas Hergert 

595pp. Ref. 529-8 

This in-depth treatment of Turbo Pascal 
Versions 4 and 5 offers separate sections 
on the Turbo environment, the new 
debugger, the extensive capabilities of the 
language itself, and special techniques 
for graphics, date arithmetic, and recur¬ 
sion. Assumes some programming 
knowledge. 

Advanced Techniques 
in Turbo Pascal 
Charles C. Edwards 

309pp. Ref. 350-3 

This collection of system-oriented tech¬ 
niques and sample programs shows how to 
make the most of IBM PC capabilities using 
Turbo Pascal. Topics include screens, win¬ 
dows, directory management, the mouse 
interface, and communications. 

Turbo BASIC Instant Reference 
SYBEX Prompter Series 
Douglas Hergert 
393pp. Ref. 485-2 

This quick reference for programmers 
offers concise, alphabetical entries on 
every command-statement, metastate¬ 
ment, function, and operation—in the 
Turbo BASIC language with descriptions, 
syntax, and examples cross-referenced to 
related commands. 

Introduction t© Turbo BASIC 
Douglas Hergert 

523pp. Ref. 441-0 

A complete tutorial and guide to this now 
highly professional language: Turbo 
BASIC, including important Turbo extras 
such as parameter passing, structured 
loops, long integers, recursion, and 8087 
compatibility for high-speed numerical 
operation. 

Advanced Techniques 
In Turbo Prolog 
Carl Townsend 
398pp. Ref. 428-3 

A goldmine of techniques and predicates 
for control procedures, string operations, 


list processing, database operations, 
BIOS-level support, program develop¬ 
ment, expert systems, natural language 
processing, and much more. 

Introduction to Turbo Prolog 
Carl Townsend 

315pp. Ref. 359-7 

This comprehensive tutorial includes sam¬ 
ple applications for expert systems, natu¬ 
ral language interfaces, and simulation. 
Covers every aspect of Prolog: facts, 
objects and predicates, rules, recursion, 
databases, and much more. 

Turbo Pascal Toolbox 
(Second Edition) 

Frank Dutton 

425pp. Ref. 602-2 

This collection of tested, efficient Turbo 
Pascal building blocks gives a boost to 
intermediate-level programmers, while 
teaching effective programming by 
example. Topics include accessing DOS, 
menus, bit maps, screen handling, and 
much more. 

Introduction to Pascal: 
including Turbo Pascal 
(Second Edition) 

Rodnay Zaks 

464pp. Ref. 533-6 

This best-selling tutorial builds complete 
mastery of Pascal-from basic structured 
programming concepts, to advanced I/O, 
data structures, file operations, sets, 
pointers and lists, and more. Both ISO 
Standard and Turbo Pascal. 

introduction to Pascal 
(Including UCSB Pascal) 

Rodnay Zaks 
420pp. Ref. 066-0 

This edition of our best-selling tutorial on 
Pascal programming gives special atten¬ 
tion to the UCSD Pascal implementation 
for small computers. Covers everything 
from basic concepts to advanced data 
structures and more. 

Celestial BASIC: Astronomy on 
Your Computer 
Eric Burgess 
300pp. Ref. 087-3 

A complete home planetarium. This col- 



lection of BASIC programs for astronomi¬ 
cal calculations enables armchair 
astronomers to observe and identify on 
screen the configurations and motions of 
sun, moon, planets and stars. 

Mastering Turbo C 
Stan Kelly-Bootle 

578pp. Ref. 462-3 

No prior knowledge of C or structured pro¬ 
gramming is required for this introductory 
course on the Turbo C language and devel¬ 
opment environment by this well-known 
author. A logical progression of tutorials and 
useful sample programs build a thorough 
understanding of Turbo C. 

Systems Programming in Turbo C 
Michael J. Young 
365pp. Ref. 467-4 

An introduction to advanced program¬ 
ming with Borland’s Turbo C, and a gold¬ 
mine of ready-made routines for the 
system programmer’s library: DOS and 
BIOS interfacing, interrupt handling, win¬ 
dows, graphics, expanded memory, 
UNIX utilities, and more. 

Understanding C 
Bruce H. Hunter 
320pp. Ref. 123-3 

A programmer’s introduction to C, with 
special attention to implementations for 
microcomputers-both CP/M and MS- 
DOS. Topics include data types, storage 
management, pointers, random I/O, func¬ 
tion libraries, compilers and more. 

Mastering C 
Craig Boion 

437pp. Ref. 326-0 

This in-depth guide stresses planning, 
testing, efficiency and portability in C 
applications. Topics include data types, 
storage classes, arrays, pointers, data 
structures, control statements, I/O and the 
C function library 

Data Handling Utilities 
in Microsoft C 

Robert A. RadeS iff e/Thomas J, Raah 
519pp. Ref. 444-5 

A C library for commercial programmers, 
with techniques and utilities for data entry, 


validation, display and storage. Focuses 
on creating and manipulating custom log¬ 
ical data types: dates, dollars, phone 
numbers, much more. 


COMMUNICATIONS 

Mastering Crosstalk XVI 
Peter W, Gofton 

187pp. Ref. 388-0 

Recoup the cost of this book in a matter of 
hours with ready-made routines that 
speed up and automate your on-line data¬ 
base sessions. Tutorials cover every 
aspect of installing, running and customiz¬ 
ing Crosstalk XVI. 


HARDWARE 


The RS“232 Solution 
Joe Campbell 

194pp. Ref. 140-3 

A complete how-to guide to trouble-free 
RS-232-C interfacing from scratch. In- 
depth coverage of concepts, techniques 
and testing devices, and case studies 
deriving cables for a variety of common 
computers, printers and modems. 

Mastering Serial 
Communications 

Peter W. Gofton 

289pp. Ref. 180-2 

The software side of communications, 
with details on the IBM PC’s serial pro¬ 
gramming, the XMODEM and Kermit 
protocols, non-ASCII data transfer, 
interrupt-level programming and more. 
Sample programs in C, assembly lan¬ 
guage and BASIC. 

Microprocessor interfacing 
Techniques (Third Edition) 

Austin Lesea/Rodnay Zaks 
456pp. Ref. 029-6 

This handbook is for engineers and hob¬ 
byists alike, covering every aspect of 
interfacing microprocessors with periph- 



eral devices. Topics include assembling a 
CPU, basic I/O, analog circuitry, and bus 
standards. 

From Chips to Systems: An 
Introduction to Microcomputers 
(Second Edition) 

Rodnay Zaks/Alexander Wolfe 
580pp. Ref. 377-5 

The best-selling introduction to microcom¬ 
puter hardware-now fully updated, revised, 
and illustrated. Such recent advances as 32- 
bit processors and RISC architecture are 
introduced and explained for the first time in 
a beginning text. 

Mastering Digital Device Control 
Williams G. Houghton 
366pp. Ref. 346-5 

Complete principles of system design 
using single-chip microcontrollers, with 
numerous examples. Topics include 
expanding memory and I/O, interfacing 
with multi-chip CPUs, clocks, display 
devices, analog measurements, and 
much more. 

HOME COMPUTERS 

Amiga Programmer's Handbook, 
Volume I (Second Edition) 

Eugene P. Mortimer© 

624pp. Ref. 367-8 

The complete reference for Amiga graph¬ 
ics programming. System commands 
and function calls are presented in detail, 
organized by functional class: Exec, 
Graphics, Animation, Layers, Intuition 
and the Workbench. Includes AmigaDOS 
version 1.2. 

Amiga Programmer's Handbook, 
Volume If 

Eugene P. Mortimer© 

365pp. Ref. 384-8 

In-depth discussion of Amiga device I/O 
programming-including programming 
with sound and speech-with complete 
details on the twelve Amiga devices and 
their associated commands and function 
calls. Indues AmigaDOS version 1.2. 


Programmer's Guide 
to the Amiga 
Robert A. Peck 
352pp. Ref. 310-4 

A programmer’s hands-on tour through 
the Amiga system-AmigaDOS, Exec, 
Graphics, Intuition, Devices, Sound, Ani¬ 
mation, and more-packed with in-depth 
information and sample programs (in 
Amiga C) showing proper use of system 
routines. 


SPREADSHEETS AND 

INTEGRATED 

SOFTWARE 


The ABC's of 1-2-3 
(Second Edition) 

Chris Gilbert/Laurie Williams 

245pp. Ref. 355-4 

Online Today recommends it as “an easy 
and comfortable way to get started with 
the program.” An essential tutorial for 
novices, it will remain on your desk as a 
valuable source of ongoing reference and 
support. For Release 2. 

Mastering 1-2-3 
(Second Edition) 

Carolyn Jorgensen 
702pp. Ref. 528-X 

Get the most from 1-2-3 Release 2 with 
this step-by-step guide emphasizing 
advanced' features and practical uses. 
Topics include data sharing, macros, 
spreadsheet security, expanded memory, 
and graphics enhancements. 

Lotus 1-2-3 Desktop Companion 
(SYBEX Ready Reference Series) 
Greg Harvey 
976pp. Ref. 501-8 

A full-time consultant, right on your desk. 
Hundreds of self-contained entries cover 
every 1-2-3 feature, organized by topic, 
indexed and cross-referenced, and sup¬ 
plemented by tips, macros and working 
examples. For Release 2. 



Advanced Techniques 
in Lotus 1-2-3 

Peter Amtoniak/E. Michael Lunsford 

367pp. Ref. 556-5 

This guide for experienced users focuses on 
advanced functions, and techniques for 
designing menu-driven applications using 
macros and the Release 2 command 
language. Interfacing techniques and 
add-on products are also considered. 

Lotus 1-2-3 Tips and Tricks 
Gene Wessskopf 
396pp. Ref. 454-2 

A rare collection of timesavers and tricks 
for longtime Lotus users. Topics include 
macros, range names, spreadsheet 
design, hardware considerations, DOS 
operations, efficient data analysis, print¬ 
ing, data interchange, applications devel¬ 
opment, and more. 

Lotus 1-2-3 instant Reference 

SYBEX Prompter Series 

Greg Harvey/Kay Yarborough Nelson 

296pp. Ref. 475-5; 4 3/4x8 
Organized information at a glance. When 
you don’t have time to hunt through hun¬ 
dreds of pages of manuals, turn here for a 
quick reminder: the right key sequence, a 
brief explanation of a command, or the 
correct syntax for a specialized function. 

Mastering Lotus HAL 
Mary V. Campbell 

342pp. Ref. 422-4 

A complete guide to using HAL “natural 
language” requests to communicate with 
1-2-3—for new and experienced users. 
Covers all the basics, plus advanced HAL 
features such as worksheet linking and 
auditing, macro recording, and more. 

Mastering Symphony 
(Fourth Edition) 

Douglas Cobb 
857pp. Ref. 494-1 

Thoroughly revised to cover all aspects of 
the major upgrade of Symphony Version 
2, this Fourth Edition of Doug Cobb’s 
classic is still “the Symphony bible” to this 
complex but even more powerful pack¬ 
age. All the new features are discussed 


and placed in context with prior versions 
so that both new and previous users will 
benefit from Cobb’s insights. 

The ABC's of Quattro 
Alan Simpson/Douglas J. Wolf 

286pp. Ref. 560-3 

Especially for users new to spreadsheets, 
this is an introduction to the basic con¬ 
cepts and a guide to instant productivity 
through editing and using spreadsheet 
formulas and functions. Includes how to 
print out graphs and data for presenta¬ 
tion. For Quattro 1.1. 

Mastering Quattro 
Alan Simpson 

576pp. Ref. 514-X 

This tutorial covers not only all of Quat- 
tro’s classic spreadsheet features, but 
also its added capabilities including 
extended graphing, modifiable menus, 
and the macro debugging environment. 
Simpson brings out how to use all of Quat- 
tro’s new-generation-spreadsheet capa¬ 
bilities. 

Mastering Framework I® 

Douglas Hergert/Jonathan Kamsn 

509pp. Ref. 390-2 

This business-minded tutorial includes a 
complete introduction to idea processing, 
“frames,” and software integration, along 
with its comprehensive treatment of word 
processing, spreadsheet, and database 
management with Framework. 

The ABC's of Excel 
on the IBM PC 
Douglas Hergert 

326pp. Ref. 567-0 

This book is a brisk and friendly introduc¬ 
tion to the most important features of 
Microsoft Excel for PC’s. This beginner’s 
book discusses worksheets, charts, data¬ 
base operations, and macros, all with 
hands-on examples. Written for all ver¬ 
sions through Version 2. 

Mastering Excel on the IBM PC 
Carl Townsend 

628pp. Ref. 403-8 

A complete Excel handbook with step-by- 



iskette Offer 
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Companion Diskette Set 

The Companion Diskette Set provides all program listings given in this 
book, plus all additional files needed to prepare the example programs. The two 
diskettes will enable you to make immediate use of these files for testing or 
modifying the example programs, or for developing your own Presentation 
Manager applications. 


PM/Edit 

PM/Edit is a full-featured version of the text editor presented in this book, 
which will allow you to write programs and other text files within a window of 
the Presentation Manager. It provides the following features, an online help 
facility, plus complete documentation in a ready-to-print file, cut, paste, and 
other block operations; search and replace commands; background compiling 
or printing of listings; macros; an undo command; word processing facilities; 
and many other features. 

OS/Tools , Version 1.1 

OS/Tools, version 1.1, is a set of software tools designed to facilitate writing 
OS/2 kernel and Presentation Manager applications. This tool set includes the 
following basic components (a complete description will be sent on request): 

» A set of dynamic-link library functions, which extend the OS/2 API and 
the standard C library. Functions are provided for both kernel and 
Presentation Manager programs. 

» A set of programmer's utilities for OS/2 and the Presentation Manager, 
including programs for designing text mode screens and windows, for 
writing and executing macros, for cutting and pasting data between 
screen groups, and for saving text and graphics screens in files, plus a 
GREP program and other utilities. 



• Source code: Complete, commented source code is provided for all func¬ 
tions and utilities. 

® Documentation: Thorough documentation for all utilities and functions 
is supplied in a ready-to-print file. 


ORDER FORM 

- Copies of the Companion Diskette Set @ $29.50 each _ 

- Copies of PM/Edit @ $49.50 each _ 

- Copies of OS/Tools (version 1.1) @ $49.50 each _ 

- California residents: add 6% sales tax _ 

- Shipping and Handling: add $2.50 ($5.00 for UPS COD or 

foreign orders) _ 

Total Order _ 

Name ___ 

Address __ 

City/State/Zip ___ 

All diskettes are in standard 51/4-inch IBM format. Please send a check for full pay¬ 
ment payable to Michael J. Young or request UPS COD (no purchase orders or bank 
cards; for foreign orders, please send an international money order in U.S. dollars). 
Your software will be shipped immediately. Order from: 

Michael J. Young 
P.O. Box 5068 
Mill Valley, CA 94942 
415/383-5354 


SYBEX is not affiliated with Michael J. Young and assumes no responsibility for any defect in 
the disk or program. 




SYBEX 


TO JOIN THE SYBEX MAILING LIST OR ORDER BOOKS 
PLEASE COMPLETE THIS FORM 


NAME 


COMPANY 


STREET___ 

STATE_ 

□ PLEASE MAIL ME MORE INFORMATION ABOUT SYBEX TITLES 


CITY 


ZIP 


ORDER FORM (There is no obligation to order) 
PLEASE SEND ME THE FOLLOWING: 


TITLE 


QTY 


PRICE 


SHIPPING AND HANDLING PLEASE ADD $2 00 
PER BOOK VIA UPS 

FOR OVERSEAS SURFACE ADD $5.25 PER 
BOOK PLUS $4.40 REGISTRATION FEE 

FOR OVERSEAS AIRMAIL ADD $18.25 PER 
BOOK PLUS $4.40 REGISTRATION FEE 

CALIFORNIA RESIDENTS PLEASE ADD 
APPLICABLE SALES TAX 

TOTAL AMOUNT PAYABLE 

□ CHECK ENCLOSED □ VISA 

□ MASTERCARD □ AMERICAN EXPRESS 


TOTAL BOOK ORDER 


ACCOUNT NUMBER 
EXPIR. DATE _ 


DAYTIME PHONE 


CUSTOMER SIGNATURE 


CHECK AREA OF COMPUTER INTEREST: 

□ BUSINESS SOFTWARE 

□ TECHNICAL PROGRAMMING 

□ OTHER:_ 

THE FACTOR THAT WAS MOST IMPORTANT IN 
YOUR SELECTION: 

□ THE SYBEX NAME 

□ QUALITY 

□ PRICE 

□ EXTRA FEATURES 

□ COMPREHENSIVENESS 

□ CLEAR WRITING 

□ OTHER___ 


OTHER COMPUTER TITLES YOU WOULD LIKE 
TO SEE IN PRINT: 


OCCUPATION 

□ PROGRAMMER □ TEACHER 

□ SENIOR EXECUTIVE □ HOMEMAKER 

□ COMPUTER CONSULTANT □ RETIRED 

□ SUPERVISOR □ STUDENT 

□ MIDDLE MANAGEMENT □ OTHER: 

□ ENGINEER/TECHNICAL - 

□ CLERICAL/SERVICE 

□ BUSINESS OWNER/SELF EMPLOYED 


OTHER COMMENTS: 


CHECK YOUR LEVEL OF COMPUTER USE 

□ NEW TO COMPUTERS 

H INFREQUENT COMPUTER USER 

□ FREQUENT USER OF ONE SOFTWARE 
PACKAGE: 

NAME __ 

□ FREQUENT USER OF MANY SOFTWARE 
PACKAGES 

□ PROFESSIONAL PROGRAMMER 


PLEASE FOLD, SEAL, AND MAIL TO SYBEX 


SYBEX, INC. 

2021 CHALLENGER DR. #100 
ALAMEDA, CALIFORNIA USA 
94501 


/"V. 


SEAL 




SYBEX Computer Books 
are different 


Here is why . . . 

At SYBEX, each book is designed with you in mind. Every manuscript is 
carefully selected and supervised by our editors, who are themselves 
computer experts. We publish the best authors, whose technical expertise 
is matched by an ability to write clearly and to communicate effectively. 
Programs are thoroughly tested for accuracy by our technical staff. Our 
computerized production department goes to great lengths to make 
sure that each book is well-designed. 

In the pursuit of timeliness, SYBEX has achieved many publishing firsts. 
SYBEX was among the first to integrate personal computers used by 
authors and staff into the publishing process. SYBEX was the first to 
publish books on the CP/M operating system, microprocessor interfacing 
techniques, word processing, and many more topics. 

Expertise in computers and dedication to the highest quality product 
have made SYBEX a world leader in computer book publishing. Trans¬ 
lated into fourteen languages, SYBEX books have helped millions of 
people around the world to get the most from their computers. We hope 
we have helped you, too. 

For a co mplete cafa/og of our P^blications: 

SYBEX, Inc. 2021 Challenger Drive, #100, Alameda, CA 94501 
Tel: (415) 523-8233/(800) 227-2346 Telex: 336311 
Fax: (415) 523-2373 


Segments 


DosAllocSeg 

9.1 

DosGetSeg 

9.7 

DosSizeSeg 

10.27 


MESSAGE 

MANAGEMENT 


Message Processing 

WinGetMsg 

2.8 

WinDispatchMsg 

2.9 

WinDefWindowProc 

2.17 

WinDefDlgProc 

8.10 

Message Queues 

WinCreateMsgQueue 

2.3 

WinDestroyMsgQueue 

2.14 

Sending Messages 

WinSendMsg 

4.8 

WinSendDlgltemMsg 

8.25 

WinPostMsg 

12.11 


MOUSE 

MANAGEMENT 


Buttons 

WinGetKeyState 

11.16 

Pointer Shape 

WinQuerySysPointer 

11.7 

WinSetPointer 

11.6 

Position/Visibiiity of Pointer 

WinQueryPointerPos 

11.2 

WinQueryMsgPos 

11.3 

WinSetPointerPos 

11.11 

WinShowPointer 

11.10 

WM_MOUSEMOVE 

11.5 


RESOURCE 

MANAGEMENT 

General 

DosGetResource 

10.26 

Bitmaps 

GpiLoadBitmap 

12.21 

WinDrawBitmap 

10.22 

GpiDeleteBitmap 

10.23 

Icons and Pointers 

WinLoadPointer 

10.8 

WinDrawPointer 

10.9 

WinSetPointer 

11.6 

WinDestroyPointer 

10.10 

Strings 

WinLoadString 

10.25 


THREAD 


MANAGEMENT 


DosCreateThread 

12.1 

DosExit 

12.5 


• WINDOW 
MANAGEMENT 

(see also Control Window Management) 
Creation/Destruction 


WinCreateStdWindow 2.5 

WinCreateWindow 12.12 

WinDestroyWindow 2.13 

WM_CREATE 3.16 

WMJNITDLG 8.19 

WM_CLOSE 12.10 

WM_QUIT 2.10 

WM_DESTROY 10.11 



Focus Window 

WinQueryFocus 

5.10 

WinSetFocus 

4.3 

Information 

WinQueryWindow 

4.6 

WinQueryWindowRect 

2.22 

WinQueryWindowText 

8.16 


Miscellaneous 


WinEnable Window 

4.10 

WinlnvalidateRect 

5.8 

WinMapWindowPoints 

11.4 

WinSetWindowText 

7.18 

WinUpdate Window 

4.16 

WinWindowFromID 

4.5 

WM_SIZE 

3.23 






PROGRAMMER’S GUIDE 
TO THE 

OS/2 

Presentation Manager 


Programmer’s Guide to the OS/2 Presentation Manager is a tutorial 
introduction to programming for the Presentation Manager, covering all 
you need to know to develop complete, full-featured applications for 
OS/2s graphic programming interface. It requires no previous 
experience with either Presentation Manager or Microsoft Windows 
programming, but offers a clear, systematic approach to learning and 
using the essential features of this vast, complex, and often confusing 
system. 

Build a complete Presentation Manager application, from the ground 
up. Part I uses a hands-on programming project—writing a Presentation 
Manager text editor—to introduce the basic architecture and essential 
features of any Presentation Manager application. Turn here to learn 
how to: 


Praise for Michael J. Young’s 
MS-DOS Advanced Programming : 
“A good choice for C and 
assembly language 
programmers...well written to 
show how to optimize your 
programs.” 

Computer Book Review 


• open and write text to an on-screen window 

• use memory-management functions to buffer text 

• add scroll bars, and scroll data in the program window 

• create, display, and manage a cursor 

• implement a full keyboard interface 

• design and install menus and accelerator keys 

• design, manage, and display dialog boxes 

Tap the system’s advanced features to enhance your software. Part II 
explores a selection of advanced topics, including: 

• interfacing with the clipboard 

® defining and using resources: icons, pointers, bitmaps, strings, 
and programmer-defined types 

® adding a mouse interface 

• using graphics functions 

® using and synchronizing multiple threads of execution 


Appendices include a glossary, a summary of operating-system services 
and predefined messages, and a bibliography. 
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